# unused-request-body

Source: https://api-genie.dev/docs/linter/swagger/rules/unused-request-body

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/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.

```yaml
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.

```yaml
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.
