4

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

My single endpoint looks like

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

the post body determines the logical path and response schema

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

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

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.

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

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

scout
  • 2,336
  • 4
  • 21
  • 22

1 Answers1

6

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)

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'
Helen
  • 87,344
  • 17
  • 243
  • 314