schema-example-defined
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule ensures that the schemas of a Swagger 2.0 document provide examples.
Rule details
Examples make an API easier to understand, and are used by documentation tools, mock servers and API consoles.
The schema-example-defined rule checks:
- every entry of
definitions, reportingSchema does not define exampleswhen it has noexample, - the inline schema of every body parameter, reporting
Body parameter schema does not define exampleswhen it has noexample, - the inline schema of every response, reporting
Response schema does not define exampleswhen it has noexampleand the response has noexamples.
Schemas defined with a $ref are not reported: the referenced definition is
checked instead. Schemas nested in other schemas (properties, items, …)
are not checked.
The OpenAPI linter has a rule of the same name, schema-example-defined, for OpenAPI 3.x documents.
Turn the rule off if examples are provided outside the document.
Examples
Good.
swagger: '2.0'
info:
title: Pets
version: 1.0.0
paths:
/pets:
post:
parameters:
- name: pet
in: body
required: true
schema:
$ref: '#/definitions/Pet'
responses:
'201':
description: Created
schema:
type: object
properties:
id:
type: integer
examples:
application/json:
id: 42
definitions:
Pet:
type: object
properties:
name:
type: string
example:
name: Rex
Bad. The inline body parameter schema and the PetId definition, used by
the response, provide no examples.
swagger: '2.0'
info:
title: Pets
version: 1.0.0
paths:
/pets:
post:
parameters:
- name: pet
in: body
required: true
schema:
type: object
properties:
name:
type: string
responses:
'201':
description: Created
schema:
$ref: '#/definitions/PetId'
definitions:
PetId:
type: object
properties:
id:
type: integer
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:
schema-example-defined: off