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

Related rules

Further reading

Was this helpful?