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é.

Associé : surveillez vos API OpenAPI/Swagger.

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.