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.4 KiB
scalar-property-missing-example
Requires that every scalar property in the API definition has either example or examples˙ defined.
Scalar properties are any of the following types: string, number, null, boolean, integer.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
API design principles
One of the main goals of your API definition (and your API documentation) is to help consumers understand how your API behaves and what to expect when working with it.
Providing examples for properties in your API definition not only improves the developer and user experience of working with your APIs, but also makes the documentation more complete. Many API documentation tools are able to automatically extract such example values from the API definition, and let consumers use those values to test the APIs or send (mock) requests to the API directly from the documentation.
Configuration
To configure the rule, add it to the rules object in your configuration file.
Set the desired severity for the rule.
rules:
scalar-property-missing-example:
severity: error
Configuration
| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off (in recommended configuration). |
An example configuration:
rules:
scalar-property-missing-example: error
Examples
Given this configuration:
rules:
scalar-property-missing-example: error
Example of an incorrect schema:
schemas:
User:
type: object
properties:
email:
description: User email address
type: string
format: email
Example of a correct schema:
schemas:
User:
type: object
properties:
email:
description: User email address
type: string
format: email
example: john.smith@example.com
Related rules
- no-invalid-media-type-examples
- no-invalid-parameter-examples
- no-invalid-schema-examples
- configurable rules