Documentație API: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - sursa adevarului: contract SDK moki testele portalului.
Swagger UI/Redoc - vitrină lizibilă; Poștaș - scripturi executabile.
Coasem lintere, verificări de rupere, exemple și scheme de eroare, generăm SDK-uri și servere Mock, publicăm un portal dev versionat și „Sunset”.

1) Obiective și principii

Contractul unu (OpenAPI). Orice altceva este generat.
Documentația este executabilă: cererile de eșantionare sunt testate în Postman/CLI.
Securitate implicită: scheme de erori, limite, autentificare.
Versionarea și ciclul de viață: „v1 ”/„ v2”, depreciere/apus de soare, changelog.

2) Structura OpenAPI (schelet minim)

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

• Descompunerea schemelor/răspunsurilor/parametrilor/cereriiOrganisme în 'componente'.
• Descrieți securitySchemes (OAuth2/JWT/HMAC) și aplicați la nivelul „căilor ”/„ globale”.

3) Eroare standard și metadate

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 }

Documentul întotdeauna 429 (limita de rată), 401/403, și anteturile „X-RateLimit-”, „Retry-After”.

4) Exemple: cerere/răspuns, curl și SDK

Pentru fiecare punct final: exemplu minim și extins.
Generați fragmente de curl și cod (JS/Python/Go) de la OpenAPI; nu scrie cu mâinile.
Aplicați valori reale: UUID, ISO-data, sume în „minor” (cenți).

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 - cum să postați

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

2. Redoc (pagini lungi citibile).

Include: temă întunecată, căutare, selector de versiune ('v1', 'v2'), banner de depreciere.

Ascunde „Încercați” pentru domeniul de producție, permite pe cutia de nisip.

6) Colecții de poștași: Scripturi live

Autogenerați colecția de la OpenAPI și suportați variabilele de mediu ('{{baseUrl}}', '{{accessToken}}').
Adăugați pretesturi (obținerea unui token) și post-teste (afirmarea stării/schemelor).
Spargeți dosarele: Auth, Plăți, Plăți, Cărți web.
Monitoare de export (programate) pentru rute critice.

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 cutia de nisip

Generați un server mock de la OpenAPI (exemple/„ exemplu ”/„ exemple ”).
Indicați limitările mocs: idempotență, întârzieri, erori aleatorii (pentru UAT).
Document sandbox vs diferențe prod (limite, date, întârzieri).

8) autogenerare SDK

Din OpenAPI, generați SDK-uri oficiale (TypeScript, Python, Go).
Politica de lansare SDK = SemVer, API versiune mapping.
În SDK-ul README: autentificare, retraire, idempotență, procesare 429/Retry-After.

9) Lining, breakage check și CI

Lintere: spectrale (stiluri/anti-modele), openapi-diff (verificări de rupere).

• validator de circuit
• linter,
• testele contractuale împotriva serverului ioc
• Swagger/Redoc/ansamblu de colectare,
• publicarea pe portal (staging→prod)
• Alertă de depreciere/apus de soare.

10) Versioning, Depreciere, Apus de soare

Versiune in URI ('/v1 ') si in' info. versiunea ".
Steaguri de depreciere: 'Depreciere: adevărat', 'Apus de soare: <RFC1123 data>', 'Legătură: <changelog>' antete.
În portal - un banner și un cronometru înainte de deconectare; Colecțiile poștașului pentru v1 sunt înghețate (numai remedieri de erori).

11) Securitate și confidențialitate la doc

Nu posta secrete, URL-uri interne, reale PAN/PII.
Pentru câmpuri sensibile - exemple de mascare și ciot.
Swagger „Încercați-l” → doar pentru a nisip, cu rate-limite.
Descrieți în mod clar OAuth2/OIDC, HMAC (pentru broșuri web) și mTLS (dacă este necesar).

12) Contracte Ghid de stil

Resurse plural: „/plăți ”, „/plăți”.
Identificatori: 'pay _',' po _', UUIDv4 sau ksuid.
Date - UTC ISO-8601; bani - 'sumă _ minor + monedă'.
Paginare - pe bază de cursor ('? cursor = & limit = '), sortare stabilă.
Idempotența - „Cheia Idempotenței” pentru mutații.
Obiect stabil 'meta' și 'link-uri' pentru liste.

13) Secțiunea "Webhooks' a docului

Secțiune separată cu plic de eveniment, semnături HMAC, fereastră de timp, retribuții, coduri de răspuns.
Organisme de eveniment de probă și colectarea poștașului pentru verificarea semnăturii locale.
replay/DLQ endpoints și lista de verificare UAT.

14) Dev Portal: Roluri și Publicare

Secțiuni: Prezentare generală, Noțiuni de bază, Autentificare, Endpoints, Exemple, Webhooks, SDK, Restricții, Changelog.
Roluri: Steward API (standarde), Domain Owner (conținut), Tech Writer (editare), DevRel (portal/comunitate).
Caracteristică: căutați prin câmpurile schemei, copiați eșantioane, „colectați cererea” → Postman.

15) Liste de verificare

• OpenAPI este valabil; linter fără erori.
• Exemplele acoperă 200/4xx/429/5xx.
• Securitate: scheme auth descrise, fără secrete.
• Format Swagger/Redoc și Postman (prod/sandbox).
• SDK generat și publicat.
• Actualizat changelog și versiunea selector.

• Anteturile de depreciere/apus de soare incluse.
• Banner în portal, scrisori către parteneri.
• Valorile apelurilor moștenite cad la țintă.

16) Anti-modele

Duplicarea surselor de adevăr (wiki ≠ OpenAPI).
Exemple de „prin ochi” fără a rula în Postman.
Lipsa unui singur format de eroare.
Versiunea „în parametrul de interogare” în loc de URI/domeniu.
Făli cu acces la alimente și fără limite.
Scheme de paginare și autentificare inconsecvente.

17) Mini fragmente de automatizare

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) Localizare și disponibilitate

Individual 'info. description_<lang>' sau două ansambluri portale (EN/RU).
Termeni glosari (KYC/AML, plată, idempotență).
Contrast, navigare la tastatură, temă întunecată.

Rezumat

Asamblați o conductă de documentație: un singur contract OpenAPI lintere și verificări de rupere vitrinele Swagger/Redoc colecțiile Postman și un server mock SDK un portal de versiune și Sunset. Exemple regulate, un singur format de eroare și o autentificare puternică vor transforma documentația din PDF pe raft într-un instrument de integrare de lucru, accelerând partenerii și reducând costurile de asistență.