Documentation API : OpenAPI, Swagger, Postman

TL; DR

OpenAPI est la source de la vérité : contrat → SDK → moki → tests → portail.
Swagger UI/Redoc est une vitrine lisible ; Postman - scripts exécutables.
Nous couchons des linters, des breaking-checks, des exemples et des schémas d'erreur qui génèrent des serveurs SDK et Mock, et publions un portail de versioning et « Sunset ».

1) Objectifs et principes

Contrat unique (OpenAPI). Tout le reste est généré.
Documentation exécutable : exemples de demandes testables dans Postman/CLI.
Sécurité par défaut : schémas d'erreur, limites, authentification.
Versioning et cycle de vie : 'v1 '/' v2', Deprecation/Sunset, changelog.

2) Structure OpenAPI (squelette minimum)

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

• Placez schemas/responses/parameters/requestBodies dans « components ».
• Décrivez securitySchemes (OAuth2/JWT/HMAC) et appliquez-le au niveau 'paths'/' global'.

3) Norme d'erreur et métadonnées

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 }

Documentez toujours 429 (rate limit), 401/403, et les titres « X-RateLimit- », « Retry-After ».

4) Exemples : request/response, curl et SDK

Pour chaque endpoint : exemple minimum et étendu.
Générer un curl et un code-clippet (JS/Python/Go) à partir de l'OpenAPI ; n'écrivez pas avec vos mains.
Appliquez des valeurs réelles : UUID, date ISO, montants en « mineurs » (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 - comment publier

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

2. Redoc (pages longues lisibles).

Incluez : thème sombre, recherche, sélecteur de version ('v1', 'v2'), bannière Deprection.

Cachez « Try it out » pour le domaine pro, laissez-le sur sandbox.

6) Collections Postman : Scénarios en direct

Autogénérez la collection à partir d'OpenAPI et prenez en charge les variables d'environnement ({{baseUrl}}, {{accessToken}}}).
Ajoutez des prétentions (obtenir un token) et des post-tests (assert status/schémas).
Diviser par dossiers : Auth, Payments, Payouts, Webhooks.
Exportez les moniteurs programmés pour les itinéraires critiques.

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

Générez un serveur mock à partir d'OpenAPI (par exemple/' example '/' examples ').
Indiquer les limites de la moka : idempotence, retards, erreurs accidentelles (pour l'UAT).
Documentez les différences entre sandbox et prod (limites, données, retards).

8) Auto-génération SDK

À partir d'OpenAPI, générer les SDK officiels (TypeScript, Python, Go).
Stratégie de sortie SDK = BouVer, mapping sur la version API.
Dans README SDK : authentification, retraits, idempotence, traitement des 429/Retry-After.

9) Linting, vérification de rupture et IC

Linters : spectral (styles/anti-modèles), openapi-diff (breaking-checks).

• le validateur de circuit,
• linter,
• les tests de contrat contre le serveur moq,
• assemblage Swagger/Redoc/collections,
• publication sur le portail (staging→prod),
• alerte Deprecation/Sunset.

10) Versioning, Deprecation, Sunset

Version dans l'URI ('/v1 ') et dans' info. version`.
Drapeaux d'obsolescence : titres 'Deprecation : true', 'Sunset : <RFC1123 date>', 'Link : <changelog>'.
Le portail contient une bannière et un minuteur avant la déconnexion ; Les collections Postman pour v1 sont congelées (bagfix uniquement).

11) Sécurité et vie privée dans le quai

Ne publiez pas de secrets, d'URL internes, de vrais PAN/PII.
Pour les champs sensibles - masquage et exemples-bouchons.
Swagger « Try it out » ne → qu'à la sandbox, avec des limites de taux.
Décrivez clairement les OAuth2/OIDC, les HMAC (pour webhooks) et les mTLS (si nécessaire).

12) Contrats de Stile Hyde

Ressources au pluriel : '/payments ', '/payouts'.
Identifiants : 'pay _', 'po _', UUIDv4 ou ksuid.
Les dates sont UTC ISO-8601 ; l'argent est 'amount _ minor + currency'.
Pagination - cursor-based ('? cursor = & limit ='), tri stable.
L'idempotence est 'Idempotency-Key' pour les mutations.
L'objet stable 'meta' et 'links' pour les listes.

13) Section « Webhooks » dans le quai

Section séparée avec enveloppe d'événement, signatures HMAC, fenêtre temporelle, retraits, codes de réponse.
Exemples de corps d'événement et collection Postman pour la vérification de signature locale.
Endpoints replay/DLQ et chèque UAT.

14) Dev-portal : rôles et publication

Sections : Aperçu, Démarrage, Authentification, Endpoints, Exemples, Webhooks, SDK, Restrictions, Changelog.
Rôles : API Steward (normes), Domain Owner (contenu), Tech Writer (éditeur), DevRel (portail/communauté).
Ficha : recherche par champs de schémas, copie de samples, « assembler une requête » → Postman.

15) Chèques-feuilles

• OpenAPI est validé ; linter sans erreur.
• Les exemples couvrent 200/4xx/429/5xx.
• Sécurité : les schémas auth sont décrits, pas de secrets.
• Formé par Swagger/Redoc et Postman (prod/sandbox).
• Généré par SDK et publié.
• Changelog et le sélecteur de version ont été mis à jour.

• Les titres Deprecation/Sunset sont inclus.
• Bannière dans le portail, lettres aux partenaires.
• Les métriques d'appels d'une version obsolète tombent au niveau cible.

16) Anti-modèles

Sources de vérité en double (wiki ≠ OpenAPI).
Exemples « à l'œil » sans lancement dans Postman.
Pas de format d'erreur unique.
Version query au lieu d'URI/domaine.
Swagger avec accès à la prod et sans limites.
Pagination incohérente et schémas d'authentification.

17) Mini-clips d'automatisation

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) Localisation et disponibilité

Un 'info'séparé. description_<lang>' ou deux ensembles de portails (EN/RU).
Termes dans le glossaire (KYC/AML, payout, idempotency).
Contraste, navigation clavier, thème sombre.

Résumé

Recueillez le convoyeur de la documentation : l'OpenAPI-contrat commun → линтеры et breaking-checks → Swagger/Redoc les devantures → Postman les collections et le mok-serveur → SDK → les vierges-portails avec версионированием et Sunset. Des exemples réguliers, un format d'erreur unique et une authentification rigoureuse transformeront la documentation en un outil de travail d'intégration qui accélère les partenaires et réduit les coûts de support.