Skip to content

no-example-value-and-externalValue.md

Latest commit

 

History

History
110 lines (85 loc) · 3 KB

no-example-value-and-externalValue.md

File metadata and controls

110 lines (85 loc) · 3 KB
slug
/docs/cli/rules/oas/no-example-value-and-externalValue

no-example-value-and-externalValue

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

{% admonition type="warning" name="Deprecated" %} This rule is deprecated in favor of spec-example-values. {% /admonition %}

OAS Compatibility
2.0 ❌
3.0 ✅
3.1 ✅
3.2 ❌ 
flowchart TD

Root ==> Paths --> PathItem --> Operation --> Parameter --> MediaType
PathItem --> Parameter
Operation --> RequestBody --> MediaType --> Example
Operation --> Responses --> MediaType
NamedExamples --> Example
Root ==> components

subgraph components
NamedExamples
end

style Example fill:#codaf9,stroke:#0044d4,stroke-width:5px
Loading

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

Option Type Description
severity string Possible 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

Related rules

Resources