Can there be 2 successful responses structure defined for an HTTP request in OpenAPI?

pvan 0
Viewed 19

I have document search request to DB which results in possibly 2 responses.

  1. List Response (If DB finds, multiple documents)
  2. Detailed response (If DB finds, 1 document).

Can we design in OpenAPI based on example return 200 - List Response and 201 - Detailed Response? Or Within 200 Response can we have sub type structures case 1 - List Response Structure and 2) Detailed Response Structure?

   responses:
    '200':
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/List'
    '201':
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Detailed'
api-design openapi
1 Answers

While your example is technically a valid OpenAPI definition, it's not a good API design. It would be better if the search request always returned a List. If only 1 document is found, return a list with 1 item. If nothing is found, return an empty list.

user4st0
Related