如何为具有相同基本路径但不同请求结构的 2 个 api 定义 swagger 规范？答案

【问题标题】：How do I define a swagger spec for 2 apis with same base path but different request structures?如何为具有相同基本路径但不同请求结构的 2 个 api 定义 swagger 规范？
【发布时间】：2017-12-05 02:50:32
【问题描述】：

例子：

这是第一个定义：

/**
 * @swagger
 * /a/b/items:
 *   get:
 *     description: Get all the items
 *     responses:
 *      200:
 *          Returns an array of items
 */

这是第二个定义：

/**
 * @swagger
 * /a/b/items:
 *   get:
 *     description: Get items by ids
 *     parameters:
 *      - name: ids
 *        in: query
 *        required: true
 *        schema:
 *          $ref: '#/definitions/itemIds'
 *
 *     responses:
 *      200:
 *          description: Returns an array of items, given the itemIds
 */

很明显，这里的区别在于请求结构。 注意，对于第二个定义，我想在查询中传递参数 ids。

第一个定义是一个简单的get请求，没有任何路径参数或查询参数。

第二个定义是具有相同基本路径但带有查询参数的获取请求。

当我连续定义这两个时，第二个定义覆盖第一个，Swagger UI 仅显示第二个。

非常希望将这两个定义作为唯一的定义。

任何解决方案/想法/方法来实现独特性？

将 api 更改为支持文档简直是“不行”！

任何帮助将不胜感激。提前致谢！

【问题讨论】：

删除第一个定义并使用 required: false 查询参数的第二个定义和适当的描述将提供一个临时解决方案。但由于这 2 个定义是 2 个唯一端点，因此非常希望有 2 个唯一定义。
OpenAPI/Swagger does not support 仅查询参数不同的路径。您可以使用带有可选查询参数的单个路径，也可以将第二个路径更改为使用路径参数而不是查询参数。没有其他方法。
OpenAPI规范库中的相关提案：Accommodate legacy APIs by allowing query parameters in the path,Querystring in Path Specification

标签： swagger swagger-ui jsdoc

【解决方案1】：

我认为第二个定义中的端点需要改为：

/a/b/items/{ids}:

【讨论】：

正如我已经明确提到的，参数在查询中。不是路径参数。感谢您考虑回答。
好的，查询参数，而不是路径……知道了！因为您不能有重复的端点，所以删除第一个定义怎么样，并且在第二个定义中需要更改：为 false。我知道您必须更改描述，但这是不可避免的。
我明白你在说什么。它提供了一个临时解决方案。但是，这两个是 2 个独立的 api，最好每个都有唯一的定义。不过，您的建议提供了一个临时解决方案。