Question

我正在尝试为我的单端点API提供Swagger / Open Api文档。

我的单个端点看起来像

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

帖子正文确定逻辑路径和响应架构

Body1: {"jsonClass": "AnimalsRankedByLifeSpan"} Response1: schema-1

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

文档的期望：每个jsonClass都被列为swagger（或任何其他）的单独调用，我可以使用规范来获取所有支持的jsonClasses。

看起来不像，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'

Answer 2

我在路径中使用 Empty Character(https://emptycharacter.com/) 做到了这一点。它不会出现在 curl 和 swagger UI 中。

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

2 个答案: