首页 文章

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

提问于
浏览
1

我正在尝试为我的单 endpoints API提供Swagger / Open Api文档 .

我的单个 endpoints 看起来像

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

post body确定逻辑路径和响应模式

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

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

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

看起来不像,昂首阔步支持这种设计 . 如果有,请指出我的例子 .

是否有任何其他Api文档框架可用于为每种支持的jsonClass提供请求 - 响应文档?

1 回答

  • 0

    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'
    

相关问题