unused-request-body
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether GET and HEAD operations of a Swagger 2.0 document
declare a request body.
Rule details
HTTP gives no meaning to the body of a GET or HEAD request. Many clients,
proxies and servers drop or reject such a body, so a body declared for these
operations is unlikely to reach the API.
In Swagger 2.0 the request body is described by a parameter with in: body
or by parameters with in: formData. The unused-request-body rule reports
Unused request body for every get or head operation whose own
parameters contain a body or form data parameter. Parameter references
($ref) are resolved, so a reference to a shared body or form data parameter
counts as well. Parameters declared on the path item are not checked.
The OpenAPI linter has a rule of the same name, unused-request-body, for OpenAPI 3.x documents.
Turn the rule off when your API and every client and intermediary between them are known to support
bodies on GET requests.
Examples
Good. The get operation takes query parameters and the post operation
takes a body.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets:
get:
parameters:
- name: limit
in: query
type: integer
responses:
'200':
description: A list of pets.
post:
parameters:
- name: pet
in: body
schema:
$ref: '#/definitions/Pet'
responses:
'201':
description: The pet was added.
definitions:
Pet:
type: object
properties:
name:
type: string
Bad. The get operation declares a body parameter and the head
operation references a form data parameter.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets:
get:
parameters:
- name: filter
in: body
schema:
type: object
- name: limit
in: query
type: integer
responses:
'200':
description: A list of pets.
head:
parameters:
- $ref: '#/parameters/name'
responses:
'200':
description: The list of pets exists.
parameters:
name:
name: name
in: formData
type: string
Automatic fixes
--fix removes the body and form data parameters
(including references to them) from the parameters of get and head
operations. Other parameters are kept, and shared parameters under the root
parameters are not changed.
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:
unused-request-body: off