Swagger REST API

La documentation interactive de l'API REST du Hub. On y essaie chaque route avec un jeton déjà posé à votre nom.

Voir l'élément dans l'écran : hub/swagger

Explication

Le Hub publie la description de son API au format OpenAPI. Cet écran l'affiche avec Swagger UI : chaque route, ses paramètres, ses réponses, et un bouton « Try it out » pour l'appeler depuis le navigateur.

On y trouve en particulier les routes /api/actions/<worker>/<action> : une par action de worker du Hub. C'est la porte REST de tout ce que les écrans font.

Pour que « Try it out » fonctionne sans rien saisir, le Hub fabrique à l'ouverture de la page un jeton d'accès (JWT) à votre nom, avec les scopes de vos rôles, et le pose sur chaque requête (Authorization: Bearer …).

Fiche complète

Ce que l'écran fait

GET /hub/swagger :

1. retrouve votre compte (iam.db_users) d'après l'adresse de connexion ;
2. rassemble les scopes de vos rôles ;
3. signe un jeton d'accès (IamService.generateAccessToken) ;
4. charge Swagger UI 5.11.0 depuis unpkg.com, sur la description /v3/api-docs.

Le jeton

Le jeton est écrit dans le code de la page. Recharger la page en fabrique un neuf.

Pièges

• Les essais sont réels : un « Try it out » sur une action d'écriture modifie le Hub.
• Passé 15 minutes, le jeton a expiré et les essais sont refusés : recharger la page.
• Swagger UI vient de unpkg.com. Si le navigateur ne joint pas ce site, la zone reste vide.
• Si la recherche du compte échoue, le jeton est fabriqué sans aucun scope : les routes qui exigent un scope refusent l'essai.