针对单个端点多个帖子请求的Open Api文档 [英] Open Api documentation for a single endpoint multiple posts request

问题描述

我正在尝试为我的单个终结点API提供Swagger/Open Api文档.

I am trying to have Swagger/Open Api documentation for my single endpoint API.

我的单个端点看起来像

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

帖子主体确定逻辑路径和响应模式

the post body determines the logical path and response schema

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

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

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

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

对文档的期望:每个jsonClass在swagger(或任何其他)中被列为单独的调用，我可以使用该规范获取所有受支持的jsonClass.

Expectation from documentation: Each jsonClass is listed as a separate call in swagger (or any other) and I can use the spec to get all the jsonClasses supported.

看起来，Swagger支持这种设计.如果有的话，请给我举个例子.

Doesnt look like, swagger supports this kind of design. If it does, please point me to examples.

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

Are there any other Api documentation frameworks I can use for providing request-response documentation for each kind of jsonClass supported?

推荐答案

OpenAPI 2.0和3.0无法在同一操作中将不同的请求模式映射到不同的响应模式.这是相应的功能请求:支持对每个路径具有多个规范的操作(例如，多个POST每个路径的操作)

OpenAPI 2.0 and 3.0 do not have a way to map different request schemas to different response schemas within the same operation. Here is the corresponding feature request: 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操作中口头记录此内容.

For now, if you use OpenAPI 3.0, you can use oneOf to define multiple possible schemas for the request and response. However, you cannot define that Body1 produces schema-1 response and Body2 produces schema-2 response. You can only document this verbally in the operation 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'

这篇关于针对单个端点多个帖子请求的Open Api文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！