Implementer Swagger

Cas d'usages

Cette fonctionnalité permet à un utilisateur de pouvoir tester une documentation Swagger sans avoir besoin de créer de compte (donc sans créer d'application ni posséder de clé de production ou sandbox). Elle peut concerner toutes les API exposant une documentaton Swagger (ex : Suivi v2 et Digiposte v3).

Il est possible d'injecter le fichier Swagger au format .yaml, .yml ou .json. Celui-ci permet d'appeler les différentes ressources de l'API par l'éxecution des routes décrites.

Principe de fonctionnement

L'interface de gestion des APIs en tant que fournisseur permet de télécharger un fichier Swagger respectant les spécifications. swagger.io.

Pour tester une documentation Swagger sans déclarer de compte utilisateur, il y a des prérequis :

• L'API doit posséder un plan caché dédié aux tests Swagger, idéalement avec des limites de consommation

• Une souscription doit être réalisée avec l'application dédiée (App4Swagger) du compte prévu de John Démo à cet effet.

• Les paramètres Cors doivent être correctement renseignés

Exemple du format OpenAPI

la configuration minimale d'un fichier Swagger est :

swagger: '2.0'
info:
  description: description
  version: 1.0.0
  title: Api
paths:
  /test:
    post:
      tags:
        - test
      responses:
        '200':
          description: OK

ou au format json:

{
  "swagger": "2.0",
  "info": {
    "description": "description",
    "version": "1.0.0",
    "title": "Api"
  },
  "paths": {
    "/test": {
      "post": {
        "tags": [
          "test"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

il existe un éditeur en ligne

Une fois publié par le fournisseur, il sera possible d'accéder au contenu de ce fichier Swagger depuis la page de la documentation d'une API et de tester les ressources.

Raccordement

Il faut dorénavant connecter les appels proposés par le fichier swagger et l'API-gateway.

Il y a des conditions à remplir pour connecter la documentation Swagger :

Les options Cors doivent être paramétrées, cors.

Associer une route OPTION

Car en passant par Swagger, la requête préflight (une requête HTTP avec le verbe 'OPTION') envoyée par les navigateurs n'est "généralement" pas déclarée au sein du fichier de raccordement de l'API (généré automatiquement par la gateway dans un contexte classique). Cela provoque une erreur HTTP 404 NOT FOUND.

Il reste donc à voir avec un architecte comment associer une requête préflight avec la méthode 'OPTION' pour un ensemble de ressource ou déclarer pour chaque route exécutable par Swagger, une route avec la même url et la méthode 'OPTION'.

Déclarer les entêtes utilisés

Une fois que la requête préflight est passée, il faut s'assurer que l'API supporte de nouvelles entêtes. Pour cela, il faut ajouter dans la déclaration de rattachement de l'API au niveau des extra.cors.allowHeaders, les entêtes nécessaires (au minimum la X-Okapi-Key).

extra:
  cors:
    allowHeaders:
      - X-Okapi-Key

Déclarer un plan caché

Le principe : Un plan "caché" n'est pas visible en Front. Il n'est visible qu'en back via GraphQL (donc uniquement par l'équipe de développement Okapi) ou dans le fichier de configuration Yaml d'une API (donc par le propriétaire de l'API ou par l'équipe de développement Okapi).

En détail :

• Un internaute ou un consommateur de l'API (Persona Caroline) ne voit pas le plan caché sur l'interface de developer.laposte.fr,

• Le fournisseur de l'API (Persona Hector) ne voit pas le plan caché dans son espace developer.laposte.fr/api-configuration/apiname/apiversion mais voit les infos du plan dans le fichier de configuration Yaml de son API (accessible depuis cette même page),

• L'administrateur Okapi ne voit pas le plan caché sur l'interface mais voit les infos du plan dans le Yaml de l'API et via GraphQL.

Comment procéder (en utilisant le fichier de configuration Yaml de l'API) ?

• Hector (ou un membre de l'équipe Okapi) créé via l'import de fichier Yaml un plan caché avec des limites de consommation (ex : "Plan4Swagger" limité à 2 appels / seconde).

Exemple de plan caché :

- type: plan
  value:
    name: Plan4Swagger
    period: 1
    price: 0
    privacy: hidden
    quotaLimiter:
      quotaTime: 1
      quotaCount: 2
    urlContext: mon-api
    version: '1'

Il n'est pas possible de passé d'un plan caché a un plan public ou privée et vice-versa depuis l'import de configuration YAML.

• Hector contacte l'équipe Okapi par mail afin d'activer la fonctionnalité.

Configuration

Le module react qui permet l'affichage de la documentation Swagger (swagger-ui-react), autorise l'ajout de champs customisable :

• x-unexecutable-methods: permet de rendre une ou plusieurs méthodes du protocole HTTP (ex: 'POST', 'PUT', 'DELETE'...) non éxecutables dans le rendu de la documentation Swagger. Pour l'activer, il faut renseigner, dans le fichier de la documentation Swagger, le champ x-unexecutable-methods et le tableau des verbes à exclure associé. Une fois cela fait, les verbes listés n'ont pas le bouton "Try it out" sur la doc Swagger.

 swagger: '2.0'
 x-unexecutable-methods:
  - post
  - delete
  - ...