swagger - 打开单个端点多个帖子请求的 Api 文档

Question

我正在尝试为我的单一端点 API 获取 Swagger/Open Api 文档。

我的单一端点看起来像

POST: http://localhost/api/v1/process

帖子正文决定了逻辑路径和响应模式

正文 1:{“jsonClass”:“AnimalsRankedByLifeSpan”} Response1: schema-1

Body2: {"jsonClass": "AnimalsInRegion", "region":"Africa", "type":"lions"} Response2: schema-2

来自文档的期望:每个 jsonClass 都被列为 swagger(或任何其他)中的单独调用，我可以使用规范来获得所有支持的 jsonClass。

不像，swagger支持这种设计。如果是这样，请指出示例。

我可以使用任何其他 Api 文档框架为支持的每种 jsonClass 提供请求-响应文档吗？

Answer 1

OpenAPI 2.0 和 3.0 无法在同一操作中将不同的请求模式映射到不同的响应模式。这是相应的功能请求:Support an operation to have multiple specifications per path (e.g. multiple POST operation per path)

目前，如果您使用 OpenAPI 3.0，则可以使用 oneOf 为请求和响应定义多个可能的模式。但是，您不能定义 Body1 产生 schema-1 响应，而 Body2 产生 schema-2 响应。您只能在操作 description 中口头记录这一点。

openapi: 3.0.0
...

paths:
  /foo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Body1'
                - $ref: '#/components/schemas/Body2'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/schema-1'
                  - $ref: '#/components/schemas/schema-2'