Qu'est-ce que Swagger ? OpenAPI Spec, Outils, Exemples

Qu'est-ce que Swagger ?

Swagger est un écosystème d'outils open-source construits autour de l'OpenAPI Specification (OAS) pour concevoir, documenter et consommer des APIs REST. Originalement développé par SmartBear, la spec a été donnée à la Linux Foundation en 2016 et renommée OpenAPI — mais le nom Swagger est resté pour le tooling.

L'OpenAPI Specification (actuellement 3.1) est un document YAML ou JSON qui décrit une API REST : endpoints, paramètres, schémas request/response, authentification, exemples. Les outils génèrent ensuite documentation, SDKs client, server stubs, serveurs mock et tests depuis cette spec.

Swagger vs OpenAPI : quelle est la différence ?

Anatomie d'une spec OpenAPI

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.petstore.example.com/v1
paths:
  /pets:
    get:
      summary: List all pets

Outils écosystème Swagger

Pourquoi utiliser Swagger / OpenAPI ?

• Single source of truth.
• APIs design-first.
• SDKs client auto-générés.
• Docs interactives.
• Serveurs mock.
• Contract testing.
• Format standardisé.
• Code-first ou design-first.

OpenAPI 3.0 vs 3.1 : qu'est-ce qui a changé ?

Workflows OpenAPI courants

Design-first (recommandé)

1. Écrire la spec OpenAPI collaborativement.
2. Reviewer avec stakeholders.
3. Générer server stubs + SDKs client.
4. Implémenter logique business dans stubs.
5. Utiliser spec pour contract tests en CI.

Code-first

1. Annoter code avec decorators framework-specific.
2. Framework auto-génère spec OpenAPI.
3. Spec servie à /openapi.json.
4. Swagger UI rend docs interactives.

Pièges et best practices

• Spec dévie de la réalité.
• Exemples manquants.
• Naming inconsistant.
• Nesting trop profond.
• Auth mal documentée.
• Versioning ignoré.

FAQ : Swagger / OpenAPI

Swagger est-il gratuit ?

Les outils open-source sont gratuits. Swagger Hub a un tier gratuit et plans payants.

Devrais-je utiliser Swagger ou Postman ?

Buts différents. Swagger/OpenAPI est le format spec ; Postman est pour testing/exploring.

Devrais-je utiliser design-first ou code-first ?

Design-first pour APIs stables, publiques. Code-first pour APIs internes.

Qu'est-ce qui remplace Swagger Codegen ?

OpenAPI Generator — un fork communautaire plus actif.

Puis-je utiliser Swagger pour GraphQL ou gRPC ?

Non — OpenAPI est REST-specific.

Comment versionner mon API ?

URL versioning (/v1/users) ou header versioning.

Load-testez votre API documentée avec Swagger avec LoadFocus

Si vous avez une spec OpenAPI et voulez load-tester l'implémentation, LoadFocus exécute des scripts JMeter et k6 contre votre vraie API depuis 25+ régions avec jusqu'à 12 500 VUs. Inscrivez-vous sur loadfocus.com/signup.