Documentazione API: OpenAPI, Swagger, Postman

TL; DR

Il è la fonte della verità, il contratto SDK-Moki ha il portale.
Swagger UI/Redoc è una vetrina leggibile; Postman - script eseguibili.
Usiamo linter, breaking-checks, esempi e schemi di errore, generiamo server SDK e Mok, pubblichiamo il nostro portale di versioning e Sunset.

1) Obiettivi e principi

Contratto uno (1). Tutto il resto viene generato.
La documentazione è eseguibile: esempi di richieste di test in Postman/CLI.
Protezione predefinita: schemi di errore, limiti, autenticazione.
Versioning e ciclo di vita: «v1 »/« v2», Deprecation/Sunset, changelog.

2) Struttura OpenAPI (scheletro minimo)

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

• Mettete il schemas/responses/parameters/requestBodies in'components '.
• Descrivi il securitySchemes (OAuth2/JWT/HMAC) e applicalo a livello paths/global.

3) Standard di errore e metadati

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 }

Documentare sempre 429 (rate limit), 401/403, e i titoli «X-RateLimit -», «Retry-After».

4) Esempi: richiest/response, curl e SDK

Per ogni endpoint, un esempio minimo ed esteso.
Generare curl e codice snippet (JS/Python/Go) dal OpenAPI; Non scrivete con le mani.
Applicare valori reali: UUID, data ISO, importi in «minori» (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 - come pubblicare

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

2. Redoc (pagine lunghe leggibili).

Includi tema scuro, ricerca, selettore versionale ('v1', 'v2'), banner Deprecation.

Nascondete «Try it out» per il dominio prod, consentite sulla sandbox.

6) Raccolte Postman: script live

Generare automaticamente una raccolta di e supportare gli ambienti variabili ('{{{n'}}', '{{{ }').
Aggiungere pretesti (recupero del token) e test post-test (assert stato/schemi).
Dividere le cartelle: Auth, Payments, Payouts, Webhooks.
Esportare i monitor (pianificati) per percorsi critici.

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 e sandbox

Genera un server mock da un OpenAPI (per esempi/' echample '/' examples ').
Indicare i vincoli Mok: Idempotenza, ritardi, errori casuali (UAT).
Documentare le differenze sandbox vs prod (limiti, dati, ritardi).

8) Generazione automatica SDK

Dal OpenAPI generare SDK ufficiali (TypeScript, Python, Go).
Criteri di rilascio SDK = SemVer, mapping per la versione API.
In README SDK: autenticazione, retrai, idempotenza, trattamento 429/Retry-After.

9) Linting, controllo rotture e CI

Lintern: spectral (stili/anti-pattern), openapi-differf (breaking-checks).

• convalidatore dello schema,
• linter,
• contract test contro MCU,
• assemblaggio Swagger/Redoc/raccolte,
• pubblicazione sul portale (staging→prod),
• Avviso di Deprecation/Sunset.

10) Versioning, Deprecation, Sunset

Versione in URI ('/v1 ') e in info. version`.
Le bandiere di obsolescenza sono le intestazioni «Deprecation: true», «Sunset: <RFC1123 date>», «Link: <changelog>».
Il portale contiene uno striscione e un timer fino a spegnersi; Le raccolte Postman per v1 sono congelate (solo bagfix).

11) Sicurezza e privacy al molo

Non pubblicare segreti, URL interni, PAN/PII reali.
Per i campi sensibili, maschera e esempi stub.
Swagger «Try it out» si rivolge solo alla sandbox, con rate-limits.
Descrivere chiaramente OAuth2/OIDC, HMAC (per webhoop) e mTLS (se necessario).

12) Contratti Sile Hyde

Risorse multiple: '/payments ', '/payouts'.
Identificatori: «pay _», «po _», UUIDv4 o ksuid.
Le date sono UTC ISO-8601; il denaro è «amount _ minor + currency».
Paginazione - cursor-based ('? cursor = & limit ='), ordinamento stabile.
Idampotenza - «Idempotency-Key» per le mutazioni.
Oggetto «meta» e «links» stabile per gli elenchi.

13) Sezione Webhooks del molo

Sezione separata con busta evento, firme HMAC, finestra di tempo, retrai, codici di risposta.
Esempi di corpi di eventi e la raccolta Postman per la convalida locale della firma.
Endpoint replay/DLQ e foglio di assegno UAT.

14) Portale d'ingresso: ruoli e pubblicazioni

Sezione: Panoramica, Avvio, Autenticazione, Endpoint, Esempi, Webhook, SDK, Vincoli, Changelog.
Ruoli: API Steward (standard), Domain Owner (contenuti), Tech Writer (modifica), DevRel (portale/comunità).
La ricerca nei campi dei circuiti, la copia dei sample, la raccolta della richiesta di → Postman.

15) Assegno fogli

• è valida; linter senza errori.
• Gli esempi coprono 200/4xx/429/5xx.
• Sicurezza: schemi auth descritti, nessun segreto.
• Formati da Swagger/Redoc e Postman (prod/sandbox).
• SDK generati e pubblicati.
• Sono stati aggiornati changelog e selettore versioni.

• I titoli Deprecation/Sunset sono inclusi.
• Striscione nel portale, e-mail ai partner.
• Le metriche di chiamata della versione obsoleta cadono al livello di destinazione.

16) Anti-pattern

Sorgenti duplicate della verità (wiki ).
Esempi di «faccia a faccia» senza essere avviati in Postman.
Nessun formato unico di errore.
Versione del parametro query invece di URI/dominio.
Swagger con accesso alla prua e senza limiti.
Paginazione e schemi di autenticazione non coerenti.

17) Mini snippet automazione

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) Localizzazione e disponibilità

Singoli "info. descrizione _ <lang> 'o due assiemi portali (EN/RU).
Termini nel glossario (KYC/AML, payout, idempotency).
Contrasto, navigazione a tastiera, tema oscuro.

Riepilogo

Raccogli la linea di montaggio della documentazione: un unico contratto OpenAPI di linter e breaking-checks di Swagger/Redoc vetrine della collezione di Postman e il server di SDK di un portale con versioning e Sunset. Esempi regolari, un unico formato di errore e un'autenticazione rigorosa trasformeranno la documentazione da PDF allo scaffale in uno strumento operativo di integrazione, accelerando i partner e riducendo i costi di supporto.