API-Dokumentation: OpenAPI, Swagger, Postman

TL; DR

OpenAPI ist die Quelle der Wahrheit: Vertrag → SDK → Moki → Tests → Portal.
Swagger UI/Redoc - lesbares Schaufenster; Postman sind ausführbare Skripte.
Wir nähen Linter, Breaking-Checks, Beispiele und Fehlerbilder, generieren SDKs und Mock-Server, veröffentlichen ein Dev-Portal mit Versionierung und „Sunset“.

1) Ziele und Grundsätze

Vertrag eins (OpenAPI). Alles andere wird generiert.
Dokumentation ist ausführbar: Beispielabfragen sind in Postman/CLI testbar.
Standardsicherheit: Fehlerschemata, Limits, Authentifizierung.
Versionierung und Lebenszyklus: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) OpenAPI-Struktur (minimales Skelett)

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' }

• Legen Sie schemas/responses/parameters/requestBodies in 'components' aus.
• Beschreiben Sie securitySchemes (OAuth2/JWT/HMAC) und wenden Sie es auf der Ebene' paths '/' global 'an.

3) Fehlerstandard und Metadaten

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 }

Dokumentieren Sie immer 429 (Rate Limit), 401/403 und die Überschriften 'X-RateLimit-', 'Retry-After'.

4) Beispiele: request/response, curl und SDK

Für jeden Endpunkt: minimales und erweitertes Beispiel.
Generieren Sie Curl und Code-Snippets (JS/Python/Go) aus OpenAPI; Schreiben Sie nicht mit den Händen.
Wenden Sie reale Werte an: UUID, ISO-Datum, Summen in „minor“ (cents).

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 - wie zu veröffentlichen

1. Swagger UI (interaktiv, try-it-out),

2. Redoc (lesbare lange Seiten).

Einschließen: dunkles Thema, Suche, Versionsauswahl ('v1', 'v2'), Deprecation Banner.

Blenden Sie „Try it out“ für die Prod-Domain aus, erlauben Sie es auf der Sandbox.

6) Postman-Sammlungen: Live-Szenarien

Die Sammlung aus OpenAPI automatisch generieren und Umgebungsvariablen ('{{baseUrl}}','{{accessToken}}') unterstützen.
Fügen Sie Prätests (Token-Empfang) und Post-Tests (Status/Schemata assert) hinzu.
Nach Ordnern aufteilen: Auth, Zahlungen, Zahlungen, Webhooks.
Exportieren Sie Monitore (nach Zeitplan) für kritische Routen.

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 und Sandbox

Generieren Sie einen Mock-Server aus OpenAPI (für Beispiele/' example '/' examples').
Markieren Sie die Einschränkungen von Mocs: Idempotenz, Verzögerungen, zufällige Fehler (für UAT).
Dokumentieren Sie die Unterschiede zwischen Sandbox und prod (Grenzen, Daten, Verzögerungen).

8) Autogenerierung SDK

Generieren Sie aus OpenAPI offizielle SDKs (TypeScript, Python, Go).
SDK Release Policy = SemVer, Mapping auf die API-Version.
Im README SDK: Authentifizierung, Retrays, Idempotenz, 429/Retry-After.

9) Linting, Bruchprüfung und CI

Linters: spectral (Stile/Anti-Muster), openapi-diff (breaking-checks).

• Validator des Schemas,
• Linter,
• Vertragstests gegen den Mock-Server,
• Montage Swagger/Redoc/Sammlung,
• Veröffentlichung auf dem Portal (staging→prod),
• Deprecation/Sunset-Warnung.

10) Versionierung, Abgrenzung, Sonnenuntergang

Version in URI ('/v1') und in 'info. version`.
Obsoleszenz-Flags: Überschriften 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
Im Portal - Banner und Timer vor der Abschaltung; Postman-Sammlungen für v1 sind eingefroren (nur Bugfixes).

11) Sicherheit und Privatsphäre am Dock

Veröffentlichen Sie keine Geheimnisse, interne URLs, echte PAN/PIIs.
Für sensible Felder gibt es Masken- und Stub-Beispiele.
Swagger „Try it out“ → nur an die Sandbox, mit Rate-Limits.
Beschreiben Sie klar OAuth2/OIDC, HMAC (für Webhooks) und mTLS (falls erforderlich).

12) Style-Hyde-Verträge

Ressourcen im Plural: '/Zahlungen', '/Zahlungen'.
Kennungen: „pay _“, „po _“, UUIDv4 oder ksuid.
Datum - UTC ISO-8601; Geld ist „amount _ minor + currency“.
Pagination - cursor-based ('? cursor = & limit ='), stabile Sortierung.
Idempotenz ist der „Idempotency-Key“ für Mutationen.
Stabiles Objekt 'meta' und 'links' für Listen.

13) Abschnitt „Webhooks“ im Dock

Separater Abschnitt mit Event-Umschlag, HMAC-Signaturen, Zeitfenster, Retrays, Antwortcodes.
Beispiele für Ereigniskörper und die Postman-Sammlung für die lokale Signaturprüfung.
Replay/DLQ Endpoints und UAT Checkliste.

14) Jungfrau-Portal: Rollen und Veröffentlichung

Abschnitte: Übersicht, Erste Schritte, Authentifizierung, Endpunkte, Beispiele, Webhooks, SDK, Einschränkungen, Changelog.
Rollen: Steward API (Standards), Domain Owner (Inhalt), Tech Writer (Bearbeitung), DevRel (Portal/Community).
Ficha: Suchen Sie nach Schemafeldern, kopieren Sie Samples, „sammeln Sie eine Anfrage“ → Postman.

15) Checklisten

• OpenAPI ist gültig; Linter ohne Fehler.
• Die Beispiele umfassen 200/4xx/429/5xx.
• Sicherheit: auth-Schemata beschrieben, keine Geheimnisse.
• Gebildet von Swagger/Redoc und Postman (prod/sandbox).
• SDKs generiert und veröffentlicht.
• Changelog und Versionsauswahl aktualisiert.

• Deprecation/Sunset Header enthalten.
• Banner im Portal, Briefe an Partner.
• Die Aufrufmetriken der veralteten Version fallen auf das Zielniveau.

16) Anti-Muster

Doppelte Quellen der Wahrheit (Wiki ≠ OpenAPI).
Beispiele „auf dem Auge“ ohne Start in Postman.
Es fehlt ein einheitliches Fehlerformat.
Version „in query-parameter“ statt URI/Domäne.
Swagger mit Zugang zum Prod und ohne Limits.
Inkonsistente Paginierung und Authentifizierungsschemata.

17) Mini-Snippets der Automatisierung

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) Lokalisierung und Verfügbarkeit

Einzelne' info. description_<lang>' oder zwei Portalbaugruppen (EN/RU).
Begriffe im Glossar (KYC/AML, Auszahlung, Idempotency).
Kontrast, Tastaturnavigation, dunkles Thema.

Zusammenfassung

Stellen Sie eine Dokumentationspipeline zusammen: einen einzigen OpenAPI-Vertrag → Linter und Breaking-Checks → Swagger/Redoc-Vitrinen → Postman-Sammlung und einen Mock-Server → SDK → ein Dev-Portal mit Versionierung und Sunset. Regelmäßige Beispiele, ein einheitliches Fehlerformat und eine starke Authentifizierung werden die Dokumentation vom „PDF im Regal“ zum Arbeitswerkzeug für Integrationen machen, Partner beschleunigen und die Supportkosten senken.