为单个端点打开多个posts请求的Api文档

Question

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

我的单一端点看起来就像

帖子：http://localhost/api/v1/process

post主体确定逻辑路径和响应模式。

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

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

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

看起来不像，昂首阔步支持这种设计。如果是的话，请给我举个例子。

还有其他Api文档框架可以用于为各种类型的jsonClass提供请求响应文档吗？

Answer 1

OpenAPI 2.0和3.0没有方法将不同的请求模式映射到同一操作中的不同响应模式。下面是相应的特性请求：支持每个路径具有多个规范的操作(例如，每个路径多个后操作)

现在，如果使用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'