Qu'est-ce que Swagger ? Swagger et OpenAPI expliqués

Qu'est-ce que Swagger ?

Swagger est la famille d'outils open source, surtout Swagger UI et Swagger Editor, construite autour de l'OpenAPI Specification, le format standard pour décrire les API HTTP. Vous écrivez une description lisible par machine de votre API, et des outils en tirent une documentation interactive, du code client et serveur, des serveurs simulés et des tests. « Swagger » était aussi le nom d'origine de la spécification elle-même.

Swagger et OpenAPI

Ces deux noms sont à l'origine de la plupart des confusions, voici donc la distinction :

• OpenAPI Specification (OAS) est le format : un document JSON ou YAML qui décrit les endpoints, les paramètres, les schémas de requête et de réponse et l'authentification. La dernière version publiée au moment de la rédaction est la 3.2.1.
• Swagger est l'ancien nom de la spécification (jusqu'au changement de nom du 1er janvier 2016) et, aujourd'hui, le nom des outils de SmartBear qui l'entourent. Un « fichier Swagger 2.0 » utilise l'ancienne appellation et reste lu par Swagger UI.
• Swagger UI affiche une description OpenAPI sous forme de documentation navigable et permet d'essayer chaque opération. Il lit les fichiers Swagger 2.0 et OAS 3.x.
• Swagger Editor est un éditeur pour écrire des descriptions OpenAPI avec aperçu en direct et validation.

Un bref historique : Swagger est né en 2011 et a été publié en open source en septembre de la même année. En novembre 2015, SmartBear a aidé à créer l'OpenAPI Initiative sous l'égide de la Linux Foundation, et la spécification est devenue OpenAPI.

À quoi ressemble une description OpenAPI

Seuls openapi et info (avec title et version) sont obligatoires, ainsi qu'au moins l'un de paths, components ou webhooks. Un petit exemple fonctionnel :

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    get:
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

À partir de ce seul fichier, des outils peuvent générer la page de documentation, un client typé, un squelette de serveur et un serveur simulé. Le format complet figure dans l'OpenAPI Specification.

Design-first ou code-first

• Design-first : vous écrivez la description, la relisez avec ceux qui consommeront l'API, puis générez squelettes et clients. Les équipes front peuvent travailler contre une maquette (simulation d'API) pendant que le back est développé. Cela correspond à une approche API-first.
• Code-first : vous annotez le code et le framework génère la description. Le démarrage est rapide, mais la description n'est aussi exacte que les annotations.

Erreurs courantes

• Laisser la spécification s'éloigner de l'API réelle. Une description que personne ne vérifie devient obsolète. Lancez des tests de contrat en CI et vérifiez l'API en ligne par rapport à elle.
• Pas d'exemples. Ajoutez des valeurs example aux schémas pour que la documentation et les simulations générées soient utilisables.
• Erreurs non documentées. Décrivez les réponses 4xx et 5xx, pas seulement la 200.
• Mauvais schéma de sécurité. Si l'authentification est mal décrite, les clients générés et « Try it out » échouent en 401.
• Le prendre pour un outil GraphQL ou gRPC. OpenAPI décrit des API HTTP. GraphQL et gRPC ont leurs propres langages de schéma.

Swagger, tests d'API et supervision

Une description n'est qu'une promesse sur le comportement. Les tests d'API vérifient cette promesse avant la mise en production, et la supervision d'API la vérifie en continu. LoadFocus API Monitoring peut importer une spécification OpenAPI 3.x ou Swagger 2.0 et générer un moniteur par opération, avec des vérifications sur le code de statut, le corps, les en-têtes et le temps de réponse. Les vérifications gratuites s'exécutent toutes les 5 minutes.

La même description peut aussi alimenter des tests de performance : importer cURL, HAR, Postman et OpenAPI dans des tests de charge (en anglais) montre comment. Pour tester des requêtes à la main, voir le guide du testeur d'API en ligne (en anglais).

Questions fréquentes sur Swagger et OpenAPI

Swagger est-il identique à OpenAPI ?

Pas tout à fait. OpenAPI est la spécification. Swagger est le nom d'origine de cette spécification et, aujourd'hui, celui des outils qui l'entourent, comme Swagger UI et Swagger Editor.

Swagger est-il gratuit ?

Swagger UI et les autres outils open source sont gratuits. SmartBear vend aussi des produits hébergés ; consultez leur site pour les offres actuelles.

Quelle version utiliser ?

Utilisez une version 3.x récente si vos outils la prennent en charge. La dernière version publiée est la 3.2.1 ; beaucoup d'outils ciblent encore la 3.0 ou la 3.1, vérifiez donc ce qu'acceptent votre générateur de documentation et votre générateur de code.

Swagger ou Postman ?

Ils ont des rôles différents. OpenAPI décrit l'API, et Postman est un client pour l'explorer et la tester. Postman peut partir d'une description OpenAPI.

Puis-je utiliser OpenAPI pour GraphQL ou gRPC ?

Non. OpenAPI décrit des API HTTP. GraphQL utilise son propre langage de schéma et gRPC utilise Protocol Buffers.

Puis-je tester mon API par rapport à la spécification ?

Oui. Les outils de tests de contrat comparent les vraies réponses à la description, et un moniteur généré depuis la spécification vérifie l'API en ligne de façon planifiée.