Tutoriel Swagger & PHP : Documenter son API avec OpenAPI (Swagger)

Dans ce tutoriel je vous propose de découvrir comment bien documenter vos API avec OpenAPI et les outils Swagger.

Swagger != OpenAPI

Avant de vous parler de l'outil il est important de mettre au clair la différence entre Swagger et OpenAPI. Mais pour résumer :

• OpenAPI, désigne la spécification.
• Swagger, désigne l'ensemble des outils permettant de travailler avec la spécification.

Au début, la spécification s'appelait Swagger mais lors de l'acquisition par SmartBear la spécification a été donnée à l'OpenAPI initiative et renommée en OpenAPI. La marque Swagger a été conservée pour les produits commerciaux / open source qui permettent de travailler avec la spécification.

Principes de bases

OpenAPI permet de détailler le fonctionnement d'une API à travers un fichier au format yaml ou json.

openapi: 3.0.0
info:
  title: Exemple d'API
  description: Une description multiligne qui accepte du **CommonMark**  !
  version: 0.1.1
servers:
  - url: https://api.grafikart.fr/v1
    description: Une description du serveur (optionnelle)
paths:
  /users:
    get:
      summary: Renvoie la liste des utilisateur.
      description: Une description plus longue expliquant le principe
      responses:
        '200':
          description: Un tableau contenant la liste des utilisateurs
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

L'ensemble des options possibles sont détaillées dans la documentation.

Il est possible de travailler sur votre spécification avec différents outils proposés par Swagger mais vous pouvez aussi générer vos spécifications gràce à des outils spécifiques à votre langage (par exemple vous pouvez utiliser des annotations PHP).