Swagger - 在文档中添加静态可选子路径段

Question

我试着用昂首阔步来记录我的api 我有一个/api/quotes的基本端点，它返回集合中的所有引号，另一个返回api/quotes/random，返回一个随机引用。

不要混淆任何人我也可以选择传递查询参数/api/quotes?random=true来随机化集合的顺序。这个按预期工作。

我已经使用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'
 */

到目前为止，我有这个。 如何在本文档中添加可选的子路径/随机文件？
如何将这些端点组合在一起？ 这是安息吗？

Answer 1

实际上，招摇是自动为我做的。我刚补充说：

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

swagger设法将路线分组。

我仍然想知道它是否是RESTFUL ......