Qu'est-ce qu'OpenAPI exactement et « Swagger » est-il la même chose ?

**OpenAPI** est un format standard (YAML ou JSON) qui décrit une API REST : chaque URL, chaque méthode, chaque paramètre, chaque forme de réponse, le tout dans un document. **Swagger** est l'**ancien nom** : les versions 1.0 et 2.0 s'appelaient Swagger, la version 3.0 a été renommée **OpenAPI** quand la spec est passée à l'[[OpenAPI Initiative||un groupe de travail de la Linux Foundation qui maintient le standard OpenAPI ; avant 2017, la spec appartenait à SmartBear et s'appelait Swagger]]. « Swagger » aujourd'hui désigne en général l'**outillage** autour d'OpenAPI : **Swagger UI** (la page de doc interactive), **Swagger Codegen**, **Swagger Editor**. La **spec elle-même** est OpenAPI. Cet outil accepte les specs 3.0 et 3.1 (la lib sous-jacente `openapi-typescript` gère les deux). Pour les anciennes specs 2.0, convertissez d'abord en 3.0 avec un outil comme **`swagger2openapi`**.

Quelle différence entre OpenAPI 3.0 et 3.1 ?

Trois changements significatifs entre **3.0** (sortie en 2017) et **3.1** (sortie en 2021) : - **Alignement sur JSON Schema** : la 3.0 utilisait un *sous-ensemble* de JSON Schema, avec des quirks. La **3.1 est entièrement compatible** avec JSON Schema 2020-12, donc tout document JSON Schema est un schéma 3.1 valide. Grosse victoire pour l'outillage. - **`nullable`** disparaît en 3.1. Là où la 3.0 écrivait `type: string, nullable: true`, la 3.1 écrit `type: [string, null]` (une vraie union de types). Plus aligné avec la façon dont TypeScript et Zod pensent les types. - **Webhooks** en first-class (une section **`webhooks`** au top niveau), utile pour décrire les API event-driven (Stripe, GitHub, etc.) de la même façon qu'on décrit les endpoints normaux. Cet outil gère les deux. Si vous mélangez des idiomes 3.0 dans un fichier 3.1 (ou l'inverse), le générateur fonctionne en général quand même, mais vous pouvez obtenir des formes de type légèrement différentes pour les champs nullable.

Comment l'outil résout-il les pointeurs \$ref ?

Un **\$ref** est un pointeur du type **`#/components/schemas/Pet`** qui dit à un lecteur « va voir la définition là-bas ». Les refs locales (qui commencent par `#/`) sont résolues automatiquement par le générateur : il parcourt le document, trouve la forme cible et inline la bonne référence dans le type émis **`components["schemas"]["Pet"]`**. Les **refs externes** (URLs ou autres fichiers comme `pet.yaml`) **ne sont pas suivies** par cet outil, pour des raisons de sécurité et de prévisibilité. Si votre spec dépend de refs externes, lancez d'abord **`swagger-cli bundle spec.yaml -o bundled.yaml`** pour tout inliner dans un seul document, puis collez le fichier bundlé ici.

Quand utiliser `parameters` ou `requestBody` ?

Différentes parties d'une requête HTTP se mappent à différents champs OpenAPI : - **`parameters`** décrit les données qui vont dans l'**URL** (path params comme `/pets/{petId}`, query strings comme `?status=available`), dans les **en-têtes** (`Authorization`) ou dans les **cookies**. Le générateur vous donne un **`parameters.path.petId: number`** typé pour chacun. - **`requestBody`** décrit les données qui vont dans le **corps HTTP** (JSON, form, multipart). Utilisé pour **POST**, **PUT**, **PATCH**. Le générateur vous donne un **`requestBody.content["application/json"]`** typé qui correspond au schéma. Erreur courante : mettre un payload JSON dans `parameters` plutôt que dans `requestBody`. `parameters` est pour des valeurs simples qui tiennent dans une URL, pas pour des objets imbriqués.

Les securitySchemes sont-ils transformés en types ?

Les **securitySchemes** (sous **`components`**) décrivent **comment** l'API authentifie : clé d'API dans un en-tête, token Bearer, flux OAuth 2.0, TLS mutuel. Le générateur ne les **émet pas comme types TypeScript** parce qu'ils décrivent un comportement runtime, pas une forme de données. Vous devez quand même brancher votre wrapper fetch pour qu'il envoie le bon en-tête (`Authorization: Bearer ...`). Ce que vous **obtenez** : chaque opération qui exige une authentification porte un champ **`security`** dans les types de chemin, donc un wrapper fetch type-aware peut rejeter les appels qui oublient le token.

Pourquoi `discriminator` compte-t-il pour les formes `oneOf` ?

Sans discriminator, **`oneOf: [Cat, Dog]`** génère une union TypeScript **`Cat | Dog`**. Ça marche en lecture, mais le narrowing dans le code vous oblige à vérifier les champs à la main : `if ("meow" in animal)`. Avec un champ **`discriminator: { propertyName: "kind" }`**, la spec promet que chaque membre a un champ littéral **`kind`** avec une valeur connue (`"cat"` ou `"dog"`). Le type généré devient une **[[discriminated union||un pattern TypeScript où chaque membre d'une union a un champ littéral (le « tag ») qui identifie de manière unique quel membre vous avez ; permet au compilateur de narrower en toute sécurité avec un simple `switch`]]** : `{ kind: "cat", ... } | { kind: "dog", ... }`. Maintenant `switch (animal.kind)` narrow correctement. **Ajoutez toujours un discriminator** si vos formes `oneOf` sont un peu complexes.

Pourquoi les types polymorphes sont-ils délicats en TypeScript ?

OpenAPI a trois mots-clés de composition : **`oneOf`** (exactement un), **`anyOf`** (un ou plusieurs), **`allOf`** (combinaison). TypeScript n'a que les unions (`A | B`) et les intersections (`A & B`) : - **`oneOf`** se mappe à une union TS. Sans discriminator, le narrowing est gauche. - **`anyOf`** se mappe aussi à une union TS, ce qui est techniquement faux (la spec dit « un ou plusieurs matches », les unions TS sont « exactement un »). Pour la plupart des cas, c'est OK, mais un validator strict comme **Zod** attraperait les vraies différences. - **`allOf`** se mappe à une intersection TS (`A & B`). Marche pour les types objets mais casse bizarrement si un membre a des champs conflictuels avec des types différents. Le générateur fait ce qu'il faut pour les cas courants. Si votre spec s'appuie beaucoup sur **`anyOf`** avec plusieurs matches par payload, prévoyez de valider à l'exécution avec Zod ou AJV en plus d'utiliser les types statiques.

Comment brancher les types générés dans un wrapper fetch ?

Un petit helper suffit. Le générateur émet un type **`paths`** indexé par URL et méthode. Construisez un wrapper qui le lit : ```ts import type { paths } from './openapi'; type GetPet = paths['/pets/{petId}']['get']; type PetResponse = GetPet['responses']['200']['content']['application/json']; async function getPet(petId: number): Promise { const res = await fetch(`/pets/${petId}`); if (!res.ok) throw new Error(`HTTP ${res.status}`); return res.json() as Promise ; } ``` Pour un client typé complet sans écrire chaque helper à la main, regardez **`openapi-fetch`** (même auteur que `openapi-typescript`) : il accepte les types générés et expose un appel `client.GET("/pets/{petId}", ...)` entièrement typé.

Puis-je générer un client complet (pas juste les types) depuis ça ?

Cet outil ne génère que les **types** parce qu'ils sont minuscules, tree-shakeables et vous laissent garder votre propre logique fetch. Pour obtenir un **client runtime complet** au-dessus de ces types, l'option la plus légère est **`openapi-fetch`** (environ 5 ko, type-safe, sans codegen). Pour une approche codegen classique plus lourde, **`@hey-api/openapi-ts`** génère des classes de service avec des méthodes comme `petService.getPetById(1)`. Choisissez types-only si vous voulez le contrôle, choisissez un client complet si vous voulez un one-liner par endpoint. Les deux fonctionnent avec la sortie de cet outil.

OpenAPI est-il la même chose que Swagger, et qu'en est-il de RAML ou AsyncAPI ?

Vue rapide des formats de description d'API REST : - **Swagger 2.0** et **OpenAPI 3.x** sont la même lignée. Utilisez la 3.x pour les nouveaux projets. - **RAML** (RESTful API Modeling Language) est un concurrent, moins populaire aujourd'hui. Convertible en OpenAPI mais rarement worth it. - **API Blueprint** est un autre concurrent, largement abandonné. - **AsyncAPI** est la **spec sœur d'OpenAPI** pour les **API event-driven** (Kafka, WebSockets, MQTT). Espace de problème différent (messagerie, pas requête/réponse), mais le format de spec est intentionnellement similaire pour que les mêmes personnes maintiennent les deux. - **GraphQL** utilise son propre langage de schéma (SDL) ; pour ça, utilisez le générateur [GraphQL vers TypeScript](/fr/graphql-vers-typescript). Pour des payloads JSON simples sans doc de schéma, essayez [JSON vers TypeScript](/fr/json-vers-typescript). Pour les API REST traditionnelles en 2026, **OpenAPI 3.1** est la réponse. C'est ce que cet outil vise.

OpenAPI vers TypeScript - gratuit

Générez des types TypeScript prêts depuis une spec OpenAPI

Vous avez une spec OpenAPI pour votre API et il vous faut des types TypeScript pour elle. Tout de suite. Sans écrire chaque route et chaque forme à la main, sans manquer un paramètre, sans oublier que tel champ paths est optionnel.

Collez le YAML ou JSON à gauche, obtenez un type `paths` propre (URL vers méthode vers formes de requête et réponse) plus des composants de schéma typés à droite. Le générateur suit les pointeurs \$ref, parcourt chaque operationId, et émet un seul fichier `.ts` auto-contenu que vous pouvez déposer dans votre projet.

Trois options rapides : schemas only (sauter le bloc `paths` quand vous ne voulez que les formes de données), JSDoc from descriptions (pour que votre IDE affiche la doc d'API au survol), et de vraies déclarations `enum` plutôt que des unions de string littéraux quand vous préférez ce style.

Mode d'emploi

Collez votre spec OpenAPI à gauche. YAML ou JSON, version 3.0 ou 3.1. L'exemple par défaut est la spec minimale Petstore pour voir le générateur fonctionner tout de suite.
Choisissez un format : laissez sur Auto et l'outil détecte YAML ou JSON depuis le premier caractère (`{` signifie JSON, autre chose est du YAML). Forcez explicitement si votre spec est inhabituelle.
Activez « Schema components only » quand vous ne voulez que les formes de données (le bloc `components.schemas`) sans le mapping `paths`. Utile quand vous écrivez votre propre client HTTP à la main.
Activez « Add JSDoc from descriptions » pour conserver vos champs `description` et `title` comme commentaires JSDoc au-dessus de chaque propriété générée. Votre IDE fera remonter la doc d'API au survol.
Activez « Use enums instead of string unions » pour les champs avec `enum: [available, pending, sold]`. Activé, vous obtenez `enum Status { available, pending, sold }`. Désactivé, vous obtenez `"available" | "pending" | "sold"` (le défaut, plus sympa pour le tree-shaking).
Cliquez sur `Copier` pour mettre le résultat dans le presse-papiers ou sur `Télécharger` pour l'enregistrer en fichier `openapi.ts`. Collez-le dans votre projet, importez les types `paths` et `components`, c'est fait.
La sortie se régénère automatiquement pendant que vous tapez (avec une demi-seconde de pause). Pas besoin de cliquer sur un bouton de build.

Quand c'est utile

Cinq situations concrètes où ça vous fait gagner des heures de saisie manuelle :

Prise en main d'une API existante. L'équipe backend a publié une spec OpenAPI. Collez-la ici, obtenez chaque forme de requête et réponse typée en quelques secondes. Construisez un wrapper `fetch` typé autour d'elles et votre IDE auto-complète chaque endpoint.
Maintenir les types en phase avec le backend. La spec est le contrat. Relancez l'outil chaque fois que le backend livre un nouvel endpoint, collez le nouveau `openapi.ts` dans votre projet, le compilateur TypeScript signale chaque endroit à mettre à jour.
Générer un SDK typé depuis une API publique. Stripe, GitHub, Linear et la plupart des SaaS modernes publient une spec OpenAPI. Déposez-la ici et vous avez un client typé en une minute, sans `any` nulle part.
Écrire une fixture de test depuis une vraie forme. Vous avez besoin d'un `Pet` mocké pour un test. Générez les types, survolez le type dans votre éditeur, l'IDE vous montre chaque champ requis. Plus besoin de deviner ce que l'API renvoie vraiment.
Migration de Swagger 2.0 / OpenAPI 3.0 vers 3.1. Les deux versions sont prises en charge. Collez l'ancienne spec, régénérez, comparez le diff : vous voyez maintenant quels champs ont gagné une sémantique `nullable` ou migré vers un tagged union.

Pour tester les vrais endpoints une fois les types en place, le testeur de requêtes HTTP parle toutes les méthodes, et le générateur de mock API peut remplacer le vrai backend pendant que vous construisez le frontend.

Questions et réponses

OpenAPI est un format standard (YAML ou JSON) qui décrit une API REST : chaque URL, chaque méthode, chaque paramètre, chaque forme de réponse, le tout dans un document. Swagger est l'ancien nom : les versions 1.0 et 2.0 s'appelaient Swagger, la version 3.0 a été renommée OpenAPI quand la spec est passée à l'OpenAPI Initiative. « Swagger » aujourd'hui désigne en général l'outillage autour d'OpenAPI : Swagger UI (la page de doc interactive), Swagger Codegen, Swagger Editor. La spec elle-même est OpenAPI. Cet outil accepte les specs 3.0 et 3.1 (la lib sous-jacente `openapi-typescript` gère les deux). Pour les anciennes specs 2.0, convertissez d'abord en 3.0 avec un outil comme `swagger2openapi`.

Générez des types TypeScript prêts depuis une spec OpenAPI

Mode d'emploi

Collez votre spec OpenAPI à gauche. YAML ou JSON, version 3.0 ou 3.1. L'exemple par défaut est la spec minimale Petstore pour voir le générateur fonctionner tout de suite.

Choisissez un format : laissez sur Auto et l'outil détecte YAML ou JSON depuis le premier caractère (`{` signifie JSON, autre chose est du YAML). Forcez explicitement si votre spec est inhabituelle.

Activez « Schema components only » quand vous ne voulez que les formes de données (le bloc `components.schemas`) sans le mapping `paths`. Utile quand vous écrivez votre propre client HTTP à la main.

Activez « Add JSDoc from descriptions » pour conserver vos champs `description` et `title` comme commentaires JSDoc au-dessus de chaque propriété générée. Votre IDE fera remonter la doc d'API au survol.

Activez « Use enums instead of string unions » pour les champs avec `enum: [available, pending, sold]`. Activé, vous obtenez `enum Status { available, pending, sold }`. Désactivé, vous obtenez `"available" | "pending" | "sold"` (le défaut, plus sympa pour le tree-shaking).

Cliquez sur `Copier` pour mettre le résultat dans le presse-papiers ou sur `Télécharger` pour l'enregistrer en fichier `openapi.ts`. Collez-le dans votre projet, importez les types `paths` et `components`, c'est fait.

La sortie se régénère automatiquement pendant que vous tapez (avec une demi-seconde de pause). Pas besoin de cliquer sur un bouton de build.

Quand c'est utile

Cinq situations concrètes où ça vous fait gagner des heures de saisie manuelle :

Prise en main d'une API existante. L'équipe backend a publié une spec OpenAPI. Collez-la ici, obtenez chaque forme de requête et réponse typée en quelques secondes. Construisez un wrapper `fetch` typé autour d'elles et votre IDE auto-complète chaque endpoint.
Maintenir les types en phase avec le backend. La spec est le contrat. Relancez l'outil chaque fois que le backend livre un nouvel endpoint, collez le nouveau `openapi.ts` dans votre projet, le compilateur TypeScript signale chaque endroit à mettre à jour.
Générer un SDK typé depuis une API publique. Stripe, GitHub, Linear et la plupart des SaaS modernes publient une spec OpenAPI. Déposez-la ici et vous avez un client typé en une minute, sans `any` nulle part.
Écrire une fixture de test depuis une vraie forme. Vous avez besoin d'un `Pet` mocké pour un test. Générez les types, survolez le type dans votre éditeur, l'IDE vous montre chaque champ requis. Plus besoin de deviner ce que l'API renvoie vraiment.
Migration de Swagger 2.0 / OpenAPI 3.0 vers 3.1. Les deux versions sont prises en charge. Collez l'ancienne spec, régénérez, comparez le diff : vous voyez maintenant quels champs ont gagné une sémantique `nullable` ou migré vers un tagged union.

Questions et réponses

OpenAPI vers TypeScript

Générez des types TypeScript prêts depuis une spec OpenAPI

Mode d'emploi

Quand c'est utile

Questions et réponses

Outils similaires

JSON vers TypeScript

GraphQL vers TypeScript

Formateur JSON

Testeur regex

OpenAPI vers TypeScript

Générez des types TypeScript prêts depuis une spec OpenAPI

Mode d'emploi

Quand c'est utile

Questions et réponses

Outils similaires

JSON vers TypeScript

GraphQL vers TypeScript

Formateur JSON

Testeur regex