# media-types-defined

Source: https://api-genie.dev/docs/linter/swagger/rules/media-types-defined

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. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks whether the operations of a Swagger 2.0 document that send or
receive a body declare its media types.

## Rule details

Swagger 2.0 declares the media types of request bodies with `consumes`, and
those of response bodies with `produces`. Both can be set on an operation or,
as defaults for all operations, on the root object. Without them, clients and
code generators have to guess the format of the payloads.

The `media-types-defined` rule reports:

- `Operation accepts a request body but defines no consumes` when an
  operation has a `body` or `formData` parameter, either its own or one
  inherited from its path item (references to `#/parameters` are resolved),
  and its effective `consumes` list is empty,
- `Operation returns a response body but defines no produces` when any
  response of an operation (references to `#/responses` are resolved) has a
  `schema`, and its effective `produces` list is empty.

An operation's own `consumes` or `produces` replaces the root one, as in the
specification, so an operation that sets `produces: []` has no response media
types even when the root object declares some.

OpenAPI 3.x documents declare media types as the keys of `content` maps, so the OpenAPI linter has
no counterpart of this rule.

Turn the rule off if all consumers of your API assume a single media type, such as
`application/json`, without it being declared.

## Examples

**Good**. The root object declares the default media types.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
consumes: [application/json]
produces: [application/json]
paths:
  /pets:
    post:
      parameters:
        - name: pet
          in: body
          required: true
          schema:
            $ref: '#/definitions/Pet'
      responses:
        '201':
          description: The created pet.
          schema:
            $ref: '#/definitions/Pet'
definitions:
  Pet:
    type: object
    properties:
      name:
        type: string
```

**Bad**. The operation sends and receives a body, but no media types are
declared.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    post:
      parameters:
        - name: pet
          in: body
          required: true
          schema:
            $ref: '#/definitions/Pet'
      responses:
        '201':
          description: The created pet.
          schema:
            $ref: '#/definitions/Pet'
definitions:
  Pet:
    type: object
    properties:
      name:
        type: string
```
