Rédaction de votre premier document Swagger

Swagger (OpenAPI) est une spécification et un ensemble d'outils pour décrire, générer et visualiser des services web RESTful.

Ci-dessous, je vais détailler comment écrire votre premier document Swagger à partir de zéro.

Les documents Swagger utilisent principalement le format YAML ou JSON et définissent divers aspects de l'API, notamment :

  • Informations de base sur l'API (titre, version, etc.)
  • Chemins et opérations disponibles
  • Paramètres d'entrée et réponses de sortie
  • Méthodes d'authentification
  • Définitions du modèle de données

Étapes de création

1. Créer la structure de fichier de base

Tout d'abord, créez un fichier nomméswagger.yamlouswagger.jsonfichier. Ce tutoriel utilise le format YAML comme exemple car il est plus facile à lire et à écrire.

Exemple
openapi: 3.0.0
informations:
  title:Ma première API
  description:Il s'agit d'un simple document d'exemple d'API
  version: 1.0.0
  contact:
    name:Équipe de support API
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Environnement de production
  - url: https://dev-api.example.com/v1
    description:Environnement de développement

2. Ajouter les informations de base du document

Exemple
openapi: 3.0.0
informations:
  title:Ma première API
  description:Il s'agit d'un simple document d'exemple d'API
  version: 1.0.0
  contact:
    name:Équipe de support API
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Environnement de production
  - url: https://dev-api.example.com/v1
    description:Environnement de développement

3. Définir les chemins et les opérations

Les chemins définissent les points de terminaison auxquels l'API peut accéder, et les opérations définissent les méthodes HTTP (GET, POST, PUT, DELETE, etc.) qui peuvent être effectuées sur ces points de terminaison.

Exemple
chemins:
  /users:
    get:
      summary:Obtenir la liste de tous les utilisateurs
      description:Renvoie toutes les informations utilisateur du système
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description:Nombre maximal de résultats renvoyés
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description:Liste des utilisateurs récupérée avec succès
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description:Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary:Créer un nouvel utilisateur
      description:Créer un nouvel utilisateur dans le système
      operationId: createUser
      requestBody:
        description:Informations sur l'utilisateur
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description:Utilisateur créé avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description:Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

4. Définir les composants et les modèles

DanscomponentsCette section définit les modèles réutilisables :

Exemple
components:
  schemas:
    Utilisateur:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description:Identifiant unique de l'utilisateur
        username:
          type: string
          description:Nom d'utilisateur
        email:
          type: string
          format: email
          description:E-mail de l'utilisateur
        status:
          type: string
          enum: [active, inactive, banned]
          description:Statut de l'utilisateur
        createdAt:
          type: string
          format: date-time
          description:Date de création
      required:
        - id
        - username
        - email
        - status
   
    NewUser:
      type: object
      properties:
        username:
          type: string
          description:Nom d'utilisateur
        email:
          type: string
          format: email
          description:E-mail de l'utilisateur
        mot de passe:
          type: string
          format: password
          description:Mot de passe utilisateur
          minLength: 8
      required:
        - username
        - email
        - mot de passe
   
    Erreur:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
      required:
        - code
        - message

5. Ajouter les définitions de sécurité

Définissez les exigences de sécurité de l'API :

Exemple
sécurité:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

6. Exemple de document complet

Combinez toutes les sections ci-dessus et vous obtenez un document Swagger complet.

Exemple

openapi: 3.0.0
informations:
  title:Ma première API
  description:Il s'agit d'un simple document d'exemple d'API
  version: 1.0.0
  contact:
    name:Équipe de support API
    email: support@example.com
    url: https://www.example.com/support
servers:
  - url: https://api.example.com/v1
    description:Environnement de production
  - url: https://dev-api.example.com/v1
    description:Environnement de développement

chemins:
  /users:
    get:
      summary:Obtenir la liste de tous les utilisateurs
      description:Renvoie toutes les informations utilisateur du système
      operationId: getUsers
      parameters:
        - name: limit
          in: query
          description:Nombre maximal de résultats renvoyés
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description:Liste des utilisateurs récupérée avec succès
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description:Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary:Créer un nouvel utilisateur
      description:Créer un nouvel utilisateur dans le système
      operationId: createUser
      requestBody:
        description:Informations sur l'utilisateur
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description:Utilisateur créé avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description:Requête invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Utilisateur:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description:Identifiant unique de l'utilisateur
        username:
          type: string
          description:Nom d'utilisateur
        email:
          type: string
          format: email
          description:E-mail de l'utilisateur
        status:
          type: string
          enum: [active, inactive, banned]
          description:Statut de l'utilisateur
        createdAt:
          type: string
          format: date-time
          description:Date de création
      required:
        - id
        - username
        - email
        - status

    NewUser:
      type: object
      properties:
        username:
          type: string
          description:Nom d'utilisateur
        email:
          type: string
          format: email
          description:E-mail de l'utilisateur
        mot de passe:
          type: string
          format: password
          description:Mot de passe utilisateur
          minLength: 8
      required:
        - username
        - email
        - mot de passe

    Erreur:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
      required:
        - code
        - message

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

sécurité:
  - bearerAuth: []

7. Utilisez les outils Swagger

Il existe plusieurs façons de visualiser et de tester votre document Swagger:

  1. Swagger UI: une page de documentation interactive
  2. Swagger Editor: un éditeur en ligne qui peut prévisualiser le document en temps réel
  3. Swagger Codegen: un outil pour générer du code client

8. Testez votre document en ligne

Vous pouvez utiliserSwagger Editorpour tester votre document en ligne. Copiez et collez simplement votre YAML ou JSON dans l'éditeur, et le panneau de droite affichera un document API visuel.

9. Bonnes pratiques

  • Utilisez des ID d'opération significatifs
  • Fournissez des descriptions détaillées pour chaque endpoint
  • Assurez-vous que tous les paramètres ont des descriptions
  • Documentez tous les codes de statut de réponse possibles
  • Utilisez des références de modèle pour réduire la duplication
  • Gardez le document à jour
  • Ajoutez des exemples de requêtes et de réponses pour chaque point de terminaison

10. Emplacements courants des paramètres

Swagger définit plusieurs emplacements de paramètres :

  • path: paramètres dans le chemin d'URL, tels que/users/{id}
  • query: paramètres de requête d'URL, tels que/users?limit=10
  • header: paramètres d'en-tête HTTP
  • cookie: paramètres de cookies
  • body: paramètres du corps de la requête (dans OpenAPI 3.0, requestBody est utilisé à la place)

11. Étendre votre document

À mesure que votre API évolue, continuez à étendre votre document Swagger :

  • Ajoutez plus de points de terminaison
  • Définir des modèles supplémentaires
  • Ajouter des descriptions plus détaillées
  • Ajouter des exemples de requête et de réponse

12. Intégration dans le développement réel

Dans le développement réel, vous pouvez :

  • Intégrer Swagger dans votre code
  • Utiliser des outils de génération automatique
  • Générer de la documentation à partir des commentaires du code
  • Incorporer Swagger UI dans votre application
Autres extensions