How to document multiple content types in successful GET response in swagger

Question

Let's say we have an example json swagger spec:

{
"swagger": "2.0",
"info": {
    "version": "1.0.0",
    "title": "Some API"
},
"basePath": "/api/v1",
"consumes": [
    "application/json"
],
"produces": [
    "application/json",
    "text/csv"
],
"paths": {
    "/some/endpoint": {
        "get": {
            "parameters": [
                {
                    "in": "body",
                    "name": "body",
                    "required": false,
                    "schema": {
                      "$ref": "#/definitions/BodyParamsDefinition"
                    }
                }
            ],
            "responses": {
                "200": { ?? } ...

There are two content types that can be produced:

• application/json
• text/csv

Default response for GET /some/endpoint is a csv file, but if the format query param is used like this /some/endpoint?format=json , the response would be in json format.

I have trouble finding how should I finish my specification with proper responses. When I use this approach: https://swagger.io/docs/specification/describing-responses/ i get a validation error: ...get.responses['200'] should NOT have additional properties

Answer 1

You are almost there, you just need to define a schema for the response. This schema defines the response structure for all content types associated with this status code.

For example, if the operation returns this JSON:

[
  {
    "petType": "dog",
    "name": "Fluffy"
  },
  {
    "petType": "cat",
    "name": "Crookshanks"
  }
]

and this CSV:

petType,name
dog,Fluffy
cat,Crookshanks

you would use:

# YAML
responses:
  200:
    description: OK
    schema:
      type: array
      items:
        type: object
        properties:
          petType:
            type: string
          name:
            type: string

More info:Describing Responses

In OpenAPI 3.0, content type definitions were improved and schemas can vary by content type:

openapi: 3.0.0
...

paths:
  /some/endpoint:
    get:
      responses:
       '200':
          description: OK
          content:
            # JSON data is an object
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
            # CSV data is a string of text
            text/csv:
              schema:
                type: string

Default response for GET /some/endpoint is a csv file, but if the format query param is used like this /some/endpoint?format=json , the response would be in json format.

There's currently no way to map specific responses to specific operation parameters, but there are several related proposals in the OpenAPI Specification repository:

• Accommodate legacy APIs by allowing query parameters in the path
• Querystring in Path Specification
• Support an operation to have multiple specifications per path
• Overloading