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

我正在尝试为我的单个端点API使用Swagger/Open Api文档。针对单个端点的多个帖子请求的打开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提供请求响应文档？

来源

2017-09-16 scout

如果不调整swagger-ui，我不会这么做。 –

可能相关：[Swagger：取决于字段值的变体模式形状]（https://stackoverflow.com/q/46557096/113116） – Helen

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'

来源

2017-12-14 20:01:35 Helen

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

回答

相关问题