no-content-response-defined

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error

This rule checks whether 204 No Content responses of a Swagger 2.0 document declare a body.

Rule details

By definition a 204 response carries no content. In Swagger 2.0 the body of a response is described by its schema property, so a 204 response with a schema contradicts its status code and misleads consumers and code generators.

The no-content-response-defined rule reports 204 response may not have a body defined for every 204 response of an operation that has a schema. Response references ($ref) are not followed. Headers are allowed.

The OpenAPI linter has a rule of the same name, no-content-response-defined, for OpenAPI 3.x documents.

Examples

Good. The 204 response has no schema.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{petId}:
    delete:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The pet was deleted.

Bad. The 204 response declares a schema.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{petId}:
    delete:
      parameters:
        - name: petId
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The pet was deleted.
          schema:
            type: object

Automatic fixes

--fix removes the schema property from 204 responses. The rest of the response, such as its description and headers, is kept.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        no-content-response-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?