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