Linter rulesSwagger 2.0no-content-response-defined

no-content-response-defined

Since 0.9.0 · fixed by --fix

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.

Configuration

None.

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

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

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading