CODEWITHSUNDEEP
restswaggerendpoint
Kevin Amiranoff
Kevin Amiranoff

Reputation: 14468

Swagger - add static optional subpath segment in documentation

I try to document my api with swagger.
I have a base endpoint to /api/quotes that returns all the quotes in the collection and another to api/quotes/random where a single random quote is returned.

Not to confused anyone I also have the option to pass a query parameter /api/quotes?random=true to randomize the order of the collection. This one works as expected.

I have documented the first endpoint using 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'
 */

So far I have this. How can I add my optional subpath /random within this documentation ?
How can I group theses endpoints in swagger ?
Is this restful ?

Upvotes: 1

Views: 337

Answers (1)

Kevin Amiranoff
Kevin Amiranoff

Reputation: 14468

Actually swagger did it automatically for me. I just added :

/**
 * @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'
 */

And swagger managed to group the routes. enter image description here

I still wonder if it is RESTFUL...

Upvotes: 1

Related Questions