Linter rulesSwagger 2.0unused-request-body

unused-request-body

Since 0.9.0 · fixed by --fix

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.

Configuration

None.

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

When invoked with --fix, this rule 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.

When Not to Use It

You may disable this rule when your API and every client and intermediary between them are known to support bodies on GET requests.

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