OpenAPI 3.1 / 3.2

Définition

Format standard de description d'API HTTP (ex-Swagger), géré par l'OpenAPI Initiative sous la Linux Foundation. La version 3.1 aligne les schémas sur JSON Schema 2020-12 ; la version 3.2, annoncée le 23 septembre 2025, ajoute sans rupture les tags structurés (résumé, parent, type), un support de première classe des réponses en flux (streaming), des méthodes HTTP arbitraires et le flux OAuth 2 « device ». Le document sert à générer documentation, clients typés, mocks et tests de contrat.

Analogie

Le plan coté d'un bâtiment : électriciens, plombiers et clients lisent le même document, chacun y trouve ce qu'il doit brancher.

Exemple de code

openapi: 3.2.0
info: { title: API Commandes, version: 1.4.0 }
tags:
  - name: commandes
    summary: Cycle de vie des commandes   # tag structuré (3.2)
paths:
  /orders/{id}:
    get:
      tags: [commandes]
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        '200':
          description: Commande trouvée
          content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } }
        '404': { description: Inconnue }

Cas d'usage

API publique ou partagée entre équipes/langages : contrat unique, SDK générés, validation des requêtes et mocks côté front.

Anti-pattern

Termes liés

Sources

• openapis.org/blog/2025/09/23/announcing-openapi-v3-2
• swagger.io/specification/v3.2/