Swagger - API

  • Mise à jour le 13 mars 2025
  • 2 min. à lire

Swagger est une spécification pour décrire, produire, consommer et visualiser des services d'API RESTful. Il fournit un format standardisé pour documenter les API, permettant aux développeurs de comprendre facilement les endpoints, les paramètres et les réponses sans avoir à examiner le code source.

Contexte d'utilisation

Swagger est utilisé dans le cycle de développement d'API pour:

  • Documenter automatiquement les API existantes
  • Générer du code client dans différents langages
  • Tester les endpoints d'API via une interface utilisateur interactive
  • Faciliter la collaboration entre équipes frontend et backend
  • Standardiser la conception d'API avant l'implémentation

Origine

Swagger a été créé en 2011 par Tony Tam de Wordnik. En 2015, SmartBear Software a fait don de la spécification Swagger à la Linux Foundation, qui l'a renommée OpenAPI Specification (OAS). Aujourd'hui, "Swagger" fait généralement référence aux outils qui implémentent la spécification OpenAPI, tandis que "OpenAPI" désigne la spécification elle-même.

Exemple pratique:

# Exemple de document Swagger/OpenAPI 3.0
openapi: 3.0.0
info:
  title: API de gestion d'utilisateurs
  version: 1.0.0
  description: API pour créer, lire, mettre à jour et supprimer des utilisateurs
paths:
  /users:
    get:
      summary: Récupère tous les utilisateurs
      responses:
        '200':
          description: Liste des utilisateurs récupérée avec succès
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Crée un nouvel utilisateur
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Utilisateur créé avec succès
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
// Exemple d'utilisation de Swagger UI Express dans une application Node.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const app = express();

// Configuration Swagger
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API de gestion d'utilisateurs',
      version: '1.0.0',
      description: 'Documentation de l\'API utilisateurs'
    },
    servers: [
      {
        url: 'http://localhost:3000'
      }
    ]
  },
  // Chemins vers les fichiers contenant les annotations JSDoc
  apis: ['./routes/*.js']
};

const swaggerDocs = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(3000, () => {
  console.log('Serveur démarré sur le port 3000');
  console.log('Documentation Swagger disponible sur http://localhost:3000/api-docs');
});

Variantes et nuances

  • OpenAPI 2.0 (Swagger): Version originale, utilise un format JSON ou YAML
  • OpenAPI 3.0: Version plus récente avec des fonctionnalités améliorées comme les callbacks, les liens et une meilleure prise en charge des webhooks
  • Implémentations par langage:
    • Java: Springfox, Springdoc-openapi
    • .NET: Swashbuckle, NSwag
    • Node.js: swagger-ui-express, swagger-jsdoc
    • Python: Flask-RESTPlus, drf-yasg (Django)

Termes associés:

  • OpenAPI: Spécification formelle sur laquelle Swagger est basé, définissant la structure standard pour décrire les API REST
  • Swagger UI: Interface utilisateur interactive permettant de visualiser et tester les API documentées
  • Swagger Codegen: Outil générant des clients API, stubs de serveur et documentation à partir de spécifications OpenAPI
  • REST (Representational State Transfer): Style d'architecture pour les API web que Swagger est conçu pour documenter
tracking-thumb