media-types-defined

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.

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.

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

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:
        media-types-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?