Dokumentacja API: OpenAPI, Swagger, Listman

TL; DR

OpenAPI - źródło prawdy: umowa → SDK → moki → testy → portal.
Swagger UI/Redoc - czytelna prezentacja; Listonosz - skrypty wykonywalne.
Szyjemy lintery, sprawdzamy, przykłady i systemy błędów, generujemy serwery SDK i Mock, publikujemy wersjonowany portal dev i „Sunset”.

1) Cele i zasady

Umowa pierwsza (OpenAPI). Wszystko inne jest generowane.
Dokumentacja jest wykonalna: próbki są testowane w Postman/CLI.
Domyślne zabezpieczenie: schematy błędów, limity, uwierzytelnianie.
Wersioning i cykl życia: 'v1 '/' v2', deprecacja/zachód słońca, changelog.

2) Struktura OpenAPI (minimalny szkielet)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• Rozkład schematów/odpowiedzi/parametrów/parametrówOrganizmy na 'składniki'.
• Opisać OAuth2/JWT/HMAC i stosować na poziomie „ścieżek ”/„ globalnych”.

3) Standard błędu i metadane

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

Zawsze dokument 429 (limit stawki), 401/403 oraz nagłówki „X- Limit-”, „Retry-After”.

4) Przykłady: zapytanie/odpowiedź, curl i SDK

Dla każdego punktu końcowego: minimalny i rozszerzony przykład.
Generowanie curl i kodu snajperów (JS/Python/Go) z OpenAPI; nie pisz rękami.
Zastosuj wartości rzeczywiste: UUID, data ISO, sumy w „drobnych” (centów).

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI/Redoc - jak zamieszczać

1. Swagger UI (interaktywny, próbny),

2. Redoc (czytelne długie strony).

Zawiera: ciemny motyw, wyszukiwanie, selektor wersji ('v1', 'v2'), baner deprecacji.

Ukryj „Wypróbuj” dla domeny produkcyjnej, pozwól na piaskownicę.

6) Kolekcje listonoszy: Skrypty na żywo

Należy autogenerować zbiór z OpenAPI i obsługiwać zmienne środowiskowe ('{{α Url}}', '{{α Token}}').
Dodaj pretests (uzyskanie tokena) i po testach (assert status/schematy).
Włamanie do folderów: Auth, Płatności, Wypłaty, Webhooks.
Monitory eksportowe (zaplanowane) dla tras krytycznych.

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) Moki i piaskownica

Generowanie serwera makietowego z OpenAPI (przykłady/' przykład '/' przykłady ').
Wskazać ograniczenia mocs: idempotencja, opóźnienia, błędy losowe (dla UAT).
Dokumenty sandbox vs prod różnice (limity, dane, opóźnienia).

8) Autogeneracja SDK

Z OpenAPI generuj oficjalne SDK (ΔScript, Python, Go).
Polityka wydawania SDK = SemVer, mapowanie wersji API.
W README SDK: uwierzytelnianie, przekładanie, idempotencja, przetwarzanie 429/Retry-After.

9) Linking, kontrola łamania i CI

Linters: spectral (style/anty-patterns), openapi-diff (breaking-checks).

• walidator obwodu,
• liniowiec,
• testy kontraktowe na serwerze ioc,
• Swagger/Redoc/montaż kolekcji,
• publikowanie do portalu (ustawianie → prod),
• Deprecacja/alarm o zachodzie słońca.

10) Wersioning, deprecacja, zachód słońca

Wersja w URI ('/v1 ') i w' info. wersja ".
Flagi deprecacji: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>' nagłówki.
W portalu - baner i timer przed odłączeniem; Kolekcje listonosza dla v1 są zamrożone (tylko poprawki błędów).

11) Bezpieczeństwo i prywatność w porcie

Nie wysyłaj sekretów, wewnętrznych adresów URL, prawdziwego PAN/PII.
Dla pól wrażliwych - przykłady maskowania i kłucia.
Swagger „Wypróbuj” → tylko do piaskownicy, z limitami stawki.
Jasno opisać OAuth2/OIDC, HMAC (dla haków webowych) i mTLS (jeśli jest to wymagane).

12) Umowy przewodnika stylu

Liczba mnoga zasobów: '/płatności ', '/wypłaty'.
Identyfikatory: „zapłać _'”, po _', UUIDv4 lub dziecko.
Daty - UTC ISO-8601; money - „amount _ minor + currency”.
Paginacja - na podstawie kursora ('? kursor = & limit = '), stabilne sortowanie.
Idempotencja - „Idempotencja-Key” dla mutacji.
Stabilny obiekt 'meta' i 'linki' dla list.

13) Sekcja "Webhooks' doku

Oddzielna sekcja z kopertą zdarzeń, podpisami HMAC, oknem czasowym, przekładami, kodami odpowiedzi.
Przykładowe organy zdarzeń i kolekcja listonoszy do weryfikacji lokalnego podpisu.
punkty końcowe replay/DLQ i lista kontrolna UAT.

14) Portal Dev: Role i publikacja

Sekcje: Przegląd, Rozpoczęcie, Uwierzytelnianie, Punkty końcowe, Przykłady, Haki internetowe, SDK, Ograniczenia, Changelog.
Role: Steward API (standardy), Domain Owner (zawartość), Tech Writer (edycja), DevRel (portal/społeczność).
Funkcja: wyszukiwanie przez pola schematu, kopiowanie próbek, „zbieranie żądania” → Listonosz.

15) Listy kontrolne

• OpenAPI jest ważny; linter bez błędów.
• Przykłady obejmują 200/4xx/429/5xx.
• Bezpieczeństwo: opisane systemy auth, brak tajemnic.
• Utworzono Swagger/Redoc i Listman (prod/piaskownica).
• SDK wygenerowane i opublikowane.
• Aktualizowany changelog i selektor wersji.

• Nagłówki deprecacji/zachodu słońca włączone.
• Baner w portalu, listy do partnerów.
• Spuścizna metryki połączeń spadają do celu.

16) Anty-wzory

Duplikat źródeł prawdy (wiki i OpenAPI).
Przykłady „po oku” bez biegania listonoszem.
Brak jednego formatu błędu.
Wersja „w parametrze zapytania” zamiast URI/domeny.
Swagger z dostępem do żywności i bez ograniczeń.
Niespójne systemy paginacji i uwierzytelniania.

17) Mini snippets automatyki

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) Lokalizacja i dostępność

Indywidualne 'info. description_<lang>' lub dwa zespoły portali (EN/RU).
Słownikowe terminy (KYC/AML, wypłata, idempotencja).
Kontrast, nawigacja klawiatura, ciemny motyw.

Podsumowanie

Montaż rurociągu dokumentacji: pojedynczy kontrakt OpenAPI → linters i breaking-checks → Swagger/Redoc prezentuje → Kolekcje listonosza i serwer makieta → SDK → portal wersji i zachód słońca. Regularne przykłady, pojedynczy format błędu i silne uwierzytelnianie przekształcą dokumentację z pliku PDF na półce w robocze narzędzie integracji, przyspieszając partnerów i zmniejszając koszty wsparcia.