header-example-or-examples-exist
Overview
This rule belongs to the openapi-v3-docsgen-linting ruleset and states that:
The examples or example property must be present in a header object to provide sample values for the header. It can be used to provide one or more examples, depending on the type of the header. The absence of examples or example property in a header object can make it difficult for API consumers to understand the intended use of the header.
| Property | Value |
|---|---|
| Enabled | Yes |
| Maximum Severity | Information |
| Message | Examples are missing from header object. |
| Code | OPENAPI3DOCSGEN_L661 |
| Type | Linting |
| Rule System | Semantic |
| Broad Category | OpenAPI Headers |
| Products Impacted | Developer Experience Portal |
| Tags | documentation generation documentation docs openapi3 openapi semantic linting apimatic description header |
Suggested Fixes
- Add the examples or example property to the header object and provide the appropriate value(s).
- If using examples property, provide a unique name for each example value to differentiate between them.
- Make sure that the example value(s) provided are valid values for the header type and do not contain any sensitive or confidential information.