Last updated

no-example-value-and-externalValue

Ensures that examples object properties externalValue and value are mutually exclusive.

OASCompatibility
2.0❌
3.0✅
3.1✅
components
NamedExample
Root
Paths
PathItem
Operation
Parameter
MediaType
RequestBody
Example
Responses

API design principles

According to the OpenAPI specification, the value field and externalValue field are mutually exclusive. An object that contains both violates the specification. The intended use of the value field is to provide in-line example values, while the externalValue field is meant for URIs that reference examples stored outside of the API description file.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default error (in recommended configuration).

An example configuration:

rules:
  no-example-value-and-externalValue: error

Examples

Given this configuration:

rules:
  no-example-value-and-externalValue: error

Example of an incorrect example object:

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
          externalValue: 'https://example.org/examples/foo-example.xml'
        bar:
          summary: A bar example
          value: {"bar": "baz"}
          externalValue: 'https://example.org/examples/bar-example.xml'

Example of a correct example object:

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          externalValue: 'https://example.org/examples/address-example.xml'

Resources

 
Next page