what does “content” : mean in swagger/openapi “responses”:

Question

Using Swagger/OpenAPI (and subsequently swagger-codegen) I haven't been able to find what the difference should be between

This, taken direclty from https://swagger.io/specification/#responsesObject (first example, json format)

"responses" : {
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
} } } } }

and

"responses" : {
  "200": {
    "description": "a pet to be returned",
    "schema": {
      "$ref": "#/components/schemas/Pet"
} } }

I've put this example into a trivial json swagger spec (json) and run the Swagger-Codegen (python, flask) to generate my controllers and model. Yaml seems to be the preferred internal representation, so when the generator runs it creates a yaml file.

With the former, the response type is "None"

responses:
  200:
    description: "a pet to be returned"

whereas the latter yields what I think I should be expecting:

responses:
  200:
    description: "a pet to be returned"
    schema:
      $ref: "#/components/schemas/Pet"

eg, the schema seems to be omitted from the first syntax using Content

What does content mean? What am i missing from the example, why doesn't the Content result in a non-None return type and corresponding schema.

Note on the SwaggerCodgen: the generated code matches exactly what the generated yaml says, hence I haven't included any of those details here

Helen Helen · Accepted Answer · 2017-08-15T17:08:07

The first example is OpenAPI 3.0, the second example is OpenAPI 2.0, hence the difference.

The content keyword used in OpenAPI 3.0 is a replacement for consumes/produces from OpenAPI 2.0. In the context of responses, content means that the response has a body and specifies the media type (JSON/XML/etc.) and structure of the response body.

OpenAPI 2.0 version:

swagger: "2.0"
...
paths:
  /foo:
    get:
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Pet"

OpenAPI 3.0 version:

openapi: 3.0.0
...
paths:
  /foo:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"

The codegen issue is likely caused by any of the fololowing:

codegen does not support OpenAPI 3.0 yet
the spec is not valid (e.g. uses a mix of 2.0 and 3.0 keywords)

what does “content” : mean in swagger/openapi “responses”:

1 Answers