# unused-request-body

Source: https://apigenie.pl/docs/linter/swagger/rules/unused-request-body

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.

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

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.