mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-10 04:21:20 +00:00
0455569a39
* docs: Start with a more developer and purpose oriented landing page * docs: Clear installation options, autocomplete is a separate guide * docs: update links in installation guide * docs: Move update instructions to be a guide, remove local installation * docs: Remove git documentation from starter project * docs: Add a quicker quickstart * docs: Re-organise and flesh out commands page * docs: add built-in ruleset docs, add concept, start guide * docs: Add a guide for configuring linting * Docs: rename custom rules to assertions * docs: Sort assertion docs and examples alphabetically * docs: clearer linting explanations and signposting of rule types * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * docs: Remove reference to a config object, after user confusion * docs: Add docs-building entrypoint article * docs: Add one-line descriptions alongside rule names * fix: Correct images for docs overview page * docs: Link to custom function in custom plugin docs * fix: Links in rules need updating after this file moved * docs: Add concept article for openapi file wrangling * docs: assertions are now called configurable rules * fix: Broken links and a renamed file * docs: Titles, links, and restructuring * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * fix: Redirect for renamed CLI update guide * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * chore: reduce filesize of images * docs: Detangle the custom/configurable rules vs assertions confusion * fix: labels as well as links to configurable rules * Update docs/guides/configure-rules.md Co-authored-by: Adam Altman <adam@redoc.ly> * fix: Better example wording and fix title case * Update docs/commands/index.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/rules/recommended.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/quickstart.md Co-authored-by: Adam Altman <adam@redoc.ly> * Update docs/rules.md Co-authored-by: Adam Altman <adam@redoc.ly> * chore: rename file built-in-rules.md and corresponding links (#1075) --------- Co-authored-by: Adam Altman <adam@redoc.ly>
2.5 KiB
2.5 KiB
no-example-value-and-externalValue
Ensures that examples object properties externalValue and value are mutually exclusive.
| OAS | Compatibility |
|---|---|
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
flowchart TD
Root ==> Paths --> PathItem --> Operation --> Parameter --> MediaType
PathItem --> Parameter
Operation --> RequestBody --> MediaType --> Example
Operation --> Responses --> MediaType
NamedExample --> Example
Root ==> components
subgraph components
NamedExample
end
style Example fill:#codaf9,stroke:#0044d4,stroke-width:5px
style NamedExample fill:#codaf9,stroke:#0044d4,stroke-width:5px
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 definition 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'