Swagger

Question

我试着大张旗鼓地记录我的 api。
我有一个到 /api/quotes 的基本端点，returns 集合中的所有引号，另一个到 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 ？
我怎样才能大摇大摆地对这些端点进行分组？
这是 restful 吗？

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...

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

Swagger - add static optional subpath segment in documentation

rest

endpoint