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 consumeswhen an operation has abodyorformDataparameter, either its own or one inherited from its path item (references to#/parametersare resolved), and its effectiveconsumeslist is empty,Operation returns a response body but defines no produceswhen any response of an operation (references to#/responsesare resolved) has aschema, and its effectiveproduceslist 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