standard-media-types
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether a Swagger 2.0 document uses only well-known media types.
Rule details
Non-standard or misspelled media types lead to interoperability issues: clients and servers may fail to negotiate the format of requests and responses.
The standard-media-types rule checks:
- the root
consumesandproduceslists, - the
consumesandproduceslists of every operation, - the media type keys of the
examplesof every response (response references are skipped).
It reports Non-standard media type is used (<media type>) for every value
that is not on the built-in list of well-known media types, such as
application/json, application/xml, application/x-www-form-urlencoded,
multipart/form-data, text/plain or application/octet-stream. Wildcards
(*/*, application/*) are accepted, and parameters after ; (like
charset=utf-8) are ignored. Values without a subtype, like json, are
reported.
The OpenAPI and AsyncAPI linters have rules of the same name, standard-media-types and standard-media-types.
Turn the rule off if your API deliberately uses vendor-specific media types that are not on the built-in list.
Examples
Good.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
consumes: [application/json]
produces: [application/json, application/xml]
paths:
/pets:
get:
produces: [text/plain]
responses:
'200':
description: The list of pets.
examples:
text/plain: Rex, Fluffy
Bad. application/x-custom and text/foo are not well-known media
types, and json has no subtype.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
consumes: [application/x-custom]
paths:
/pets:
get:
produces: [json]
responses:
'200':
description: The list of pets.
examples:
text/foo: Rex
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:
standard-media-types: off