Generator dokumentacji API

Endpointy, parametry, cURL i odpowiedzi JSON w jednym dokumencie Markdown

Bezpieczne (SSL)

Przetwarzanie Lokalne

100% Darmowe

Przejdź do narzędzia

Instrukcja

1

Wprowadź dane
Wpisz treść, wklej tekst lub załaduj plik z dysku.
2

Kliknij przycisk
Narzędzie natychmiast przetworzy Twoje dane w przeglądarce.
3

Pobierz wynik
Skopiuj gotowy tekst lub zapisz plik na urządzeniu.

                                                function runTool() {

                                                  return "Wynik gotowy w 0.1s";

                                                }

Nazwa API

Wersja

Bazowy URL

Autoryzacja

Endpointy Format: METHOD /path | opis | param:typ:wymagany

Przykładowa odpowiedź (JSON)

Endpointów: 4

# My API

**Wersja:** 1.0.0

**Bazowy URL:** `https://api.example.com/v1`

**Autoryzacja:** Token Bearer (`Authorization: Bearer <token>`)

## Spis treści

- [GET /users](#get-users)
- [POST /users](#post-users)
- [GET /users/{id}](#get-users-id)
- [DELETE /users/{id}](#delete-users-id)

## GET /users

Lista użytkowników

**Endpoint:** `GET https://api.example.com/v1/users`

| Parametr | Typ | Wymagany |
| --- | --- | --- |
| `page` | integer | nie |
| `limit` | integer | nie |

**Przykład cURL:**

```bash
curl -X GET "https://api.example.com/v1/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

**Przykładowa odpowiedź:**

```json
{
    "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
}
```

## POST /users

Utwórz użytkownika

**Endpoint:** `POST https://api.example.com/v1/users`

| Parametr | Typ | Wymagany |
| --- | --- | --- |
| `name` | string | tak |
| `email` | string | tak |

**Przykład cURL:**

```bash
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

**Przykładowa odpowiedź:**

```json
{
    "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
}
```

## GET /users/{id}

Szczegóły użytkownika

**Endpoint:** `GET https://api.example.com/v1/users/{id}`

| Parametr | Typ | Wymagany |
| --- | --- | --- |
| `id` | integer | tak |

**Przykład cURL:**

```bash
curl -X GET "https://api.example.com/v1/users/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

**Przykładowa odpowiedź:**

```json
{
    "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
}
```

## DELETE /users/{id}

Usuń użytkownika

**Endpoint:** `DELETE https://api.example.com/v1/users/{id}`

| Parametr | Typ | Wymagany |
| --- | --- | --- |
| `id` | integer | tak |

**Przykład cURL:**

```bash
curl -X DELETE "https://api.example.com/v1/users/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

**Przykładowa odpowiedź:**

```json
{
    "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
}
```

Dokument zawiera spis treści, parametry, przykłady cURL i poprawnie sformatowaną odpowiedź JSON. Format parametru: name:type:required.

Oceń to narzędzie:

Powiązane narzędzia

Inne narzędzia, które mogą Ci się przydać

Generator dokumentacji API w czytelnym formacie Markdown

Generator dokumentacji API zamienia uporządkowaną listę endpointów REST w gotowy dokument Markdown. Podajesz nazwę i wersję interfejsu, bazowy adres HTTPS, sposób autoryzacji, parametry oraz przykładową odpowiedź JSON. Wynik zawiera spis treści, osobną sekcję każdego endpointu, tabelę parametrów i polecenie cURL bez prawdziwych tokenów.

Narzędzie przydaje się podczas rozpoczynania integracji, porządkowania istniejącego API i przygotowania krótkiej dokumentacji dla zespołu lub klienta. Nie próbuje zastąpić pełnej specyfikacji OpenAPI. Tworzy przewidywalny plik .md, który można przejrzeć w pull requeście, przechowywać razem z kodem i później uzupełnić o statusy HTTP, limity, modele danych czy zasady wersjonowania.

Jak opisać endpointy REST

Każdy endpoint zajmuje jeden wiersz. Trzy części oddziela pionowa kreska: metoda i ścieżka, krótki opis oraz opcjonalne parametry. Parametr ma postać nazwa:typ:wymagany, a kilka parametrów rozdziela się przecinkiem. Wartość true oznacza pole wymagane, a false opcjonalne.

GET /users | Lista użytkowników | page:integer:false, limit:integer:false
POST /users | Utwórz użytkownika | name:string:true, email:string:true
GET /users/{id} | Szczegóły użytkownika | id:integer:true

Walidacja metod, ścieżek i parametrów

Generator akceptuje metody GET, POST, PUT, PATCH, DELETE, HEAD i OPTIONS. Ścieżka musi zaczynać się od ukośnika i nie może zawierać sekwencji .., znaków sterujących ani fragmentów zdolnych zmienić strukturę wygenerowanego Markdown lub polecenia powłoki. Nazwy parametrów zaczynają się literą albo podkreśleniem. Obsługiwane są popularne typy, między innymi string, integer, number, boolean, array, object, uuid, date i datetime.

Jeżeli ścieżka zawiera symbol {id}, parametr id musi znaleźć się na liście jako wymagany. Powtórzone nazwy, nieznany typ i niepoprawna wartość pola wymagalności zatrzymują generowanie z informacją o numerze wiersza. Błędny endpoint nie jest pomijany po cichu, dzięki czemu dokument nie wygląda na kompletny, gdy część wejścia została odrzucona.

Co powstaje w dokumencie Markdown

Element	Zawartość	Korzyść
Nagłówek API	Nazwa, wersja, bazowy URL i autoryzacja	Integrator od razu zna kontekst dokumentu
Spis treści	Odsyłacz do każdej metody i ścieżki	Szybka nawigacja w długim pliku
Sekcja endpointu	Opis, pełny adres oraz tabela parametrów	Jednolity kontrakt dla wszystkich operacji
Przykład cURL	Metoda, URL i kontrolowane nagłówki	Bezpieczny punkt startu bez osadzonych sekretów
Odpowiedź	Zweryfikowany i sformatowany JSON	Brak uszkodzonych bloków kodu

Odpowiedź jest parsowana jako JSON przed umieszczeniem w dokumencie i formatowana z czytelnymi wcięciami. Niepoprawny przecinek, niedomknięty cudzysłów lub zbyt głęboka struktura powodują błąd zamiast wygenerowania mylącego przykładu. Jeśli najpierw projektujesz kontrakt danych, strukturę obiektów możesz uporządkować w generatorze JSON Schema.

Autoryzacja i bezpieczne przykłady cURL

Dostępne warianty to token Bearer, klucz API w nagłówku X-API-Key oraz brak autoryzacji. Generator nigdy nie prosi o prawdziwy token ani klucz. W przykładzie używa zmiennych $TOKEN i $API_KEY, dlatego sekret nie trafia do wyniku, historii narzędzia ani pliku przechowywanego w repozytorium. Bazowy URL może korzystać wyłącznie z HTTP lub HTTPS i nie może zawierać danych logowania.

Wygenerowany cURL jest przykładem technicznym, a nie magazynem poświadczeń. Sekrety podawaj jako zmienne środowiskowe w lokalnej powłoce lub w bezpiecznym systemie CI. Nie wklejaj tokenów do dokumentacji, zgłoszeń ani historii Git.

Co warto dopisać przed publikacją

Automatyczny szkielet powinien przejść przegląd właściciela API. Dla każdej operacji dopisz znaczenie kodów 2xx, 4xx i 5xx, format błędu, reguły paginacji, limity zapytań i informację o idempotencji. Jeśli interfejs jest dostępny w przeglądarce, politykę źródeł i zasobów można przygotować w generatorze nagłówka CSP. Metadane strony dokumentacji uporządkuje natomiast generator meta tagów.

Praktyczny proces przygotowania dokumentacji

Wybierz preset lub wpisz nazwę, semantyczną wersję i bazowy adres API.
Dodaj po jednym wierszu na endpoint, używając stabilnych nazw typów i parametrów.
Wklej fikcyjną odpowiedź JSON pozbawioną danych osobowych, tokenów i sekretów.
Wybierz mechanizm autoryzacji, wygeneruj dokument i popraw wskazane błędy wejścia.
Skopiuj Markdown do repozytorium, uzupełnij kontrakt błędów i sprawdź przykłady na środowisku testowym.

Warto aktualizować dokumentację w tym samym pull requeście co implementację endpointu. Recenzent widzi wtedy zmianę kodu i kontraktu obok siebie. Przy zmianach niekompatybilnych podnieś główną wersję API, opisz migrację i pozostaw termin wycofania poprzedniego wariantu.

Najczęściej zadawane pytania

Czy generator tworzy specyfikację OpenAPI lub Swagger?

Nie. Wynikiem jest dokument Markdown przeznaczony do szybkiego czytania i wersjonowania. Może być szkieletem opisu, ale formalny kontrakt OpenAPI wymaga dodatkowych pól, schematów, odpowiedzi i reguł walidacji.

Dlaczego błędny wiersz nie jest po prostu pomijany?

Ciche pominięcie prowadziłoby do niepełnej dokumentacji bez wyraźnego ostrzeżenia. Generator podaje numer pierwszego wadliwego wiersza, aby wszystkie zamierzone endpointy znalazły się w wyniku.

Czy mogę wkleić prawdziwy token do przykładu?

Nie ma takiej potrzeby i nie należy tego robić. Przykłady używają symbolicznych zmiennych powłoki. Prawdziwe poświadczenia przechowuj poza dokumentacją i repozytorium.

Jak opisać parametr obecny w ścieżce?

Dodaj placeholder, na przykład /users/{id}, a następnie zdefiniuj id:integer:true. Generator wymaga, aby każdy placeholder miał odpowiadający mu parametr wymagany.

Czy wynik można dalej edytować?

Tak. To zwykły Markdown. Po skopiowaniu można dodać diagramy, przykłady dla innych języków, opis webhooków, kody błędów i odsyłacze do changelogu.