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

Question

我尝试用 swagger 记录我的 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'
 */

到目前为止，我有这个。 如何在本文档中添加我的可选子路径 /random ？
如何在 swagger 中对这些端点进行分组？
这样安静吗？

Answer 1

实际上，swagger 自动为我做到了。我刚刚补充了：

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