Fatigués de rédiger la documentation de vos API ? SwaggerHub le fait pour vous

Ce tutoriel fournit un aperçu de SwaggerHub et vous guide dans la création d’une spécification d’API REST sur SwaggerHub.

En tant qu’ingénieur data full-stack chez Neoxia, j’ai eu l’opportunité de travailler en mission chez JCDecaux sur des applications web pour la mesure d’audience dans des lieux publics (aéroports, stations de métro…).

Impliqué dans une équipe mixte composée à la fois d’ingénieurs data et de développeurs front-end et back-end, nous avions trois enjeux

1. nous n’avions pas a priori de format commun de documentation, accessible de façon centralisée
2. l’équipe front-end risquait d’être bloquée en attendant que l’équipe back-end ne développe les API
3. l’équipe data et l’équipe de développement devaient se coordonner pour modéliser les données et documenter ce modèle

Pour y répondre, nous avons fait le choix de l’outil SwaggerHub.

Qu’est-ce que SwaggerHub ?

SwaggerHub est une plateforme en ligne où concevoir vos API REST, qu’il s’agisse d’API publiques, d’API privées internes ou de microservices. Le principe de base de SwaggerHub est “Design First, Code Later”. En d’autres termes, on commence par concevoir une API, ses ressources, ses opérations et ses modèles de données, et une fois la conception terminée, on implémente la logique métier.

Les définitions d’API sont écrites dans le format OpenAPI (anciennement connu sous le nom de Swagger). Elles sont enregistrées dans le Cloud SwaggerHub et peuvent être synchronisées avec des systèmes externes comme GitHub ou Amazon API Gateway. On peut également collaborer avec son équipe sur SwaggerHub, et maintenir plusieurs versions des API au fur et à mesure de leur évolution.

Qu’est-ce qu’OpenAPI ?

La spécification OpenAPI (anciennement connue sous le nom de spécification Swagger) est un format de description d’API pour les API REST. Il convient aussi bien à la conception de nouvelles API qu’à la documentation de vos API existantes. OpenAPI vous permet de décrire l’ensemble de votre API, y compris les endpoints disponibles, les opérations, les formats de requête et de réponse, les méthodes d’authentification prises en charge, les contacts de support et d’autres informations.

Les définitions OpenAPI peuvent être écrites en YAML ou JSON. L’éditeur SwaggerHub utilise YAML, mais vous pouvez importer et télécharger aussi bien YAML que JSON.

Un exemple de spécification OpenAPI 3.0 (au format YAML) ressemble à ceci :

openapi: 3.0.0
info:
  title: Hello API
  version: '1.0'
servers:
  - url: https://api.neoxia.com/v1
paths:
  /hello:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string

Ce format simple est lisible par l’homme et par la machine et s’explique facilement. C’est l’une des raisons pour lesquelles OpenAPI est si populaire parmi les développeurs d’API.

Quels avantages avons-nous tiré de l’utilisation de SwaggerHub ?

1. La réduction des dépendances entre les différentes équipes. Ainsi l’équipe front-end a pu entamer les développements sans attendre que les API soient développées par l’équipe back-end, puisqu’elle disposait déjà des mocks fournis par SwaggerHub.
2. Une amélioration de la collaboration en cours de développement, grâce à la conception et la documentation claire des API RESTful.
3. Une amélioration de la transparence dans le travail quotidien des équipes.

Comment SwaggerHub fonctionne-t-il ?

La suite de cet article va présenter l’interface de SwaggerHub et un tutoriel pour la création d’une définition d’une API et ses suites.

Aperçu de l’UI de SwaggerHub

Lorsque vous êtes connecté à SwaggerHub, la page MY hub répertorie toutes les API auxquelles vous avez accès. Il s’agit à la fois des API que vous avez créées et des API pour lesquelles vous avez été invité à collaborer. Si vous êtes nouveau sur SwaggerHub et que vous n’avez pas encore d’API, la liste sera vide, mais elle changera dès que vous commencerez à en créer.

Pour rechercher des API existantes sur SwaggerHub, utilisez la page de recherche à laquelle vous pouvez accéder en cliquant Search dans la barre latérale à gauche. Vous pourrez ainsi trouver d’excellentes API publiques développées par d’autres utilisateurs de SwaggerHub.

Pour afficher une API spécifique, cliquez dessus dans la liste.

​​Une page d’API sur SwaggerHub est une vue divisée qui montre le code YAML de votre définition OpenAPI et une belle documentation d’API de style référence générée à partir de celui-ci. La documentation de l’API permet aux utilisateurs de tester les appels d’API directement dans le navigateur. Le panneau de navigation de gauche affiche une liste des opérations et des modèles définis dans votre API et vous permet de passer à l’endroit correspondant dans le code YAML.

Création d’un exemple d’API avec SwaggerHub

Étape 1. Créez une API

Dans la barre latérale de gauche, cliquez “+” et sélectionnez Create New API.

Remplissez les informations de l’API comme indiqué dans l’image ci-dessous.

La version OpenAPI spécifie le format de la spécification, OpenAPI 3.0.0 ou 2.0. Choisissez 3.0.0 (la dernière version).

Il existe des modèles prédéfinis, mais commençons par une API vierge (sans modèle).

Entrez bookstore comme nom d’API, 1.0.0 comme version, Bookstore API comme titre et une description arbitraire.

Cliquez sur Create API. L’éditeur SwaggerHub s’ouvre, prérempli avec les métadonnées de l’API que vous avez saisies :

Chaque définition d’API commence par la version de l’OpenAPI, dans notre exemple c’est openapi: 3.0.0.

openapi: 3.0.0

La section suivante, info, contient les métadonnées de l’API — le titre de l’API, sa description, sa version, etc. La section info peut également contenir des informations de contact, la licence et d’autres détails.

info:
  version: 1.0.0
  title: Bookstore API
  description: This is a bookstore sample API

La section paths est l’endroit où vous définissez les opérations de l’API. Nous la remplirons plus tard.

paths: {}

La section servers contient l’URL de base pour les appels API.

En cochant la case Auto Mock API lors de la création de notre API, la section servers a été préremplie par le plugin Auto Mock API.

servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/my_organisation/book
store/1.0.0

Étape 2. Définir une opération GET

Supposons que notre API soit destinée à gérer une collection de livres. Chaque livre a un ID, et l’API a besoin d’une opération pour retourner le livre par son ID. Il s’agirait d’une requête GET comme celle-ci :

GET /books/7
GET /books/23

En utilisant Swagger, nous pouvons décrire cette opération GET comme suit. La partie {bookId} dans /books/{bookId} indique le paramètre de chemin, c’est-à-dire un composant d’URL qui peut varier.

paths:
  /books/{bookId}:
    get:
      summary: Returns a book by ID
      responses:
        '200':
          description: OK

Collez le code ci-dessus dans l’éditeur, en remplaçant paths: {}. Votre spécification devrait ressembler à ceci :

Notez que lorsque vous modifiez la spécification, SwaggerHub met automatiquement à jour l’aperçu sur la droite.

Étape 3. Définir les paramètres

Notre opération API GET /books/{bookId} possède le paramètre bookId qui spécifie l’ID du livre à renvoyer. Pour définir ce paramètre dans votre spécification, ajoutez la section parameters comme suit :

paths:
  /books/{bookId}:
    get:
      summary: Returns a book by ID
      parameters: 
      - name: bookId
        in: path
        required: true
        description: The ID of the book to return
        schema:
          type: integer
      responses:
        '200':
          description: OK

Ce code précise le nom du paramètre (le même que celui utilisé dans le chemin d’accès à l’URL), son type, sa description et s’il est obligatoire.

in : path signifie que le paramètre est transmis dans le cadre du chemin d’accès à l’URL (GET /books/3), par opposition, par exemple, aux string paramètres de requête (GET /books?id=15).

Notez qu’après avoir ajouté la section des paramètres, l’aperçu est mis à jour pour refléter les informations sur les paramètres nouvellement ajoutés :

Étape 4. Définir les modèles de réponses

Ensuite, nous devons décrire les modèles de réponses possibles à l’appel de l’API. Une réponse est définie par un code d’état HTTP, une description et un schéma facultatif (un modèle de données pour le corps de la réponse, le cas échéant).

Supposons qu’un appel réussi à GET /books/{bookId} renvoie le statut HTTP 200 et cet objet JSON :

{
  "id": 2,
  "title": "Les Misérables",
  "author": "Victor Hugo",
  "release_date": 1862,
  "number_of_pages": 1462
}

Pour décrire cette réponse, ajoutez la section content sous la réponse 200 comme suit. La section content précise que la réponse contient des données JSON (application/json). Notez l’élément schema — il décrit la structure du corps de la réponse, comme les propriétés de l’objet JSON renvoyé.

paths:
  /books/{bookId}:
    get:
      ...
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  title:
                    type: string
                  author:
                    type: string
                  release_date:
                    type: integer
                  number_of_pages:
                    type: integer

Vous pouvez également décrire des codes d’erreur qui peuvent être renvoyés par un appel d’API :

responses:
  '404':
    description: Book with specified ID was not found

La spécification complète devrait maintenant ressembler à ceci :

Maintenant que vous avez terminé l’édition de la spécification, cliquez sur SAVE afin d’enregistrer votre travail d’une part et pour que la spécification soit déployée sur le mock serveur d’autre part.

Étape 5. Test de l’API

Au niveau de la documentation interactive (section de droite), cliquez sur Try it out pour tester l’opération GET, ensuite, remplissez le paramètre bookId et validez votre choix en appuyant sur Execute. Le résultat apparaît dans la section Responses.

Vous pouvez remarquer la présence d’une section Snippets où vous trouverez la commande cURL pour exécuter ce même test dans un terminal (Linux, Windows).

Étape 6. Mocker une réponse

Pour mocker la réponse d’une opération il suffit de rajouter la section example comme ceci :

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          type: object
          properties:
            ...
          example:
            id: 2
            title: "Les Misérables"
            author: "Victor Hugo"
            release_date: 1862
            number_of_pages: 1462

Nous allons tester le mock en faisant l’appel avec Postman depuis une machine différente de celle utilisée pour implémenter cette spécification API.

Vous pouvez remarquer que nous avons reçu une réponse identique à la section example. Ceci explique que l’API est accessible de partout sans même avoir besoin d’un compte SwaggerHub.

Conclusion

Nous avons conçu avec succès une API REST, mais SwaggerHub ne se limite pas à être un simple éditeur. Il fournit également des outils pour gérer les spécifications d’API et les intégrer dans un flux de travail :

• en ayant la possibilité de renommer l’API, de la forker ou de la transférer à un autre propriétaire.
• en ayant la possibilité de générer un code serveur et client pour une API afin d’aider à commencer l’implémentation. On peut également y télécharger sa propre définition OpenAPI au format YAML ou JSON.

Malgré l’existence d’autres services d’API Design, c’est sur SwaggerHub que s’est porté notre choix, chez Neoxia.

Si vous avez des questions sur l’utilisation de SwaggerHub ou des remarques sur cet article, n’hésitez pas à nous contacter en commentaire ou par e-mail.

Si le sujet de l’API management vous intéresse, retrouvez la série d’articles, écrits par des spécialistes de chez Neoxia et échangeons !