Skip to content
Learni
View all tutorials
Documentation API

Comment maîtriser OpenAPI 3.1 pour APIs complexes en 2026

18 minEXPERT
APIOpenAPI

Introduction

OpenAPI 3.1 représente une évolution majeure pour la documentation d'APIs. Cette version intègre pleinement JSON Schema 2020-12, supporte les webhooks natifs et améliore la validation des schémas. Dans un contexte professionnel, maîtriser OpenAPI 3.1 permet de générer du code client/serveur fiable, de réduire les erreurs de contrat et d'automatiser les tests. Ce tutoriel vous guide pas à pas vers une implémentation experte et production-ready.

Prérequis

  • Node.js 20+ et TypeScript 5.4+
  • Connaissances avancées de JSON Schema et REST
  • Outils : openapi-generator-cli, @apidevtools/swagger-parser
  • YAML et notions de webhooks

Initialiser le projet OpenAPI

terminal
mkdir openapi-3.1-project && cd openapi-3.1-project
npm init -y
npm install -D @apidevtools/swagger-parser openapi-generator-cli typescript
npx openapi-generator-cli version

Cette commande initialise un projet TypeScript et installe les outils de validation et génération de code pour OpenAPI 3.1. Swagger Parser permet de valider la conformité stricte à la spécification 3.1.

Créer la spécification OpenAPI 3.1 de base

openapi.yaml
openapi: 3.1.0
info:
  title: User Management API
  version: 2.0.0
  description: API experte avec JSON Schema 2020-12
servers:
  - url: https://api.example.com/v2
paths:
  /users/{id}:
    get:
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Utilisateur récupéré
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
      required: [id, email]

Ce fichier définit une spécification OpenAPI 3.1 valide. La version 3.1.0 active les fonctionnalités JSON Schema avancées. Chaque champ est strictement typé pour garantir une génération de code précise.

Implémenter les webhooks natifs

openapi.yaml
webhooks:
  userCreated:
    post:
      operationId: userCreatedWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Webhook reçu

Les webhooks sont déclarés au niveau racine en 3.1. Cela permet de documenter les événements push sans endpoints REST classiques et facilite la génération de listeners côté client.

Utiliser JSON Schema 2020-12

openapi.yaml
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        metadata:
          type: object
          properties:
            preferences:
              type: array
              items:
                type: string
              minItems: 1
              uniqueItems: true
      dependentRequired:
        email: [verified]
      unevaluatedProperties: false

OpenAPI 3.1 supporte les mots-clés JSON Schema 2020-12 comme dependentRequired et unevaluatedProperties. Ces contraintes renforcent la validation stricte et évitent les données inattendues en production.

Valider la spécification

validate.ts
import SwaggerParser from '@apidevtools/swagger-parser';

async function validateSpec() {
  try {
    const api = await SwaggerParser.validate('openapi.yaml');
    console.log('Spécification OpenAPI 3.1 valide');
    console.log(`Version: ${api.openapi}`);
  } catch (err) {
    console.error('Erreur de validation:', err);
    process.exit(1);
  }
}

validateSpec();

Ce script TypeScript valide la conformité complète à OpenAPI 3.1. Il détecte les erreurs de schémas et les références cassées avant toute génération de code.

Générer le code client TypeScript

terminal
npx openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client \
  --additional-properties=supportsES6=true,typescriptThreePlus=true

La génération produit un client TypeScript typé et prêt pour la production. Les options ES6 et TypeScript 3+ garantissent une compatibilité optimale avec les projets modernes.

Bonnes pratiques

  • Toujours utiliser openapi: 3.1.0 et JSON Schema 2020-12 pour une validation stricte
  • Centraliser les schémas réutilisables dans components/schemas
  • Documenter systématiquement les webhooks et les securitySchemes
  • Automatiser la validation dans le pipeline CI/CD
  • Versionner les specs avec SemVer

Erreurs courantes à éviter

  • Utiliser des mots-clés JSON Schema 2019-09 incompatibles avec 3.1
  • Omettre la clé webhooks au niveau racine
  • Ignorer unevaluatedProperties qui laisse passer des champs non déclarés
  • Ne pas valider la spec avant génération de code

Pour aller plus loin

Approfondissez vos compétences avec nos formations avancées sur les APIs.