Swagger - ajouter un segment de sous-chemin statique en option dans la documentation

Question

J'essaie de documenter mon API avec une touche de fantaisie.
J'ai un point de terminaison de base à /api/quotes qui retourne toutes les guillemets dans la collection et un autre à api/quotes/random où une seule citation aléatoire est retournée.

Pour ne pas confondre personne, j'ai également la possibilité de passer un paramètre de requête /api/quotes?random=true pour randomiser l'ordre de la collection. Celui-ci fonctionne comme prévu.

J'ai documenté le premier point final à l'aide jsdoc/yaml

/** 
* @swagger 
* /api/quotes/: 
* get: 
*  tags: 
*  - Greek mythological Quotes 
*  description: get mythological quotes 
*  produces: 
*  - application/json 
*  parameters: 
*  - name: random 
*   in: query 
*   description: "Optional param to randomize list order" 
*   type: boolean 
*  responses: 
*  200: 
*   description: list of all mythological quotes 
*   schema: 
*   $ref: '#/definitions/Quote' 
*/ 

Jusqu'à présent, j'ai cela. Comment puis-je ajouter mon sous-chemin optionnel/aléatoire dans cette documentation?
Comment regrouper ces extrémités dans swagger?
Est-ce reposant?

Answer 1

En fait, swagger l'a fait automatiquement pour moi. Je viens d'ajouter:

/** 
* @swagger 
* /api/quotes/random: 
* get: 
*  tags: 
*  - Greek mythological Quotes 
*  description: Fetch one random mythological quote 
*  produces: 
*  - application/json 
*  responses: 
*  200: 
*   description: One random mythological quote 
*   schema: 
*   $ref: '#/definitions/Quote' 
*/ 

Et Swagger réussi à regrouper les routes.

Je me demande encore si elle est RESTFUL ...