no-inline-enum-schema-definition
Overview
This rule belongs to the openapi-v3-apimatic-linting ruleset and states that:
Enum schema definitions must be added globally in the components/schemas section with a unique name and then referenced throughout the API document with that name. Inline definitions of enum schemas are not recommended as for auto-generating SDKs/documentation the names of such schemas are deduced from the parent objects in which they are declared inline. The names deduced this way may not be user-friendly and can conflict with other definitions resulting in name duplication. This behavior can affect your output quality.
| Property | Value |
|---|---|
| Enabled | Yes |
| Maximum Severity | Warning |
| Message | Inline enum schema definition found. |
| Code | OPENAPI3APIMATIC_L692 |
| Type | Linting |
| Rule System | Semantic |
| Broad Category | OpenAPI Schemas |
| Products Impacted | API Transformer, Code Generation, Developer Experience Portal |
| Tags | openapi3 openapi apimatic semantic linting enum schema inline components |
Suggested Fixes
- Remove the inline enum schema definition and relocate it to the components/schemas section.
- Define the enum schema globally in the components/schemas section with a unique name. Then reference it using $ref in your current object with a path like '#/components/schemas/<global name>'.
- Ensure that no other inline enum schemas are defined.
- If you wish to retain the inline schema definition, try adding a
titleproperty in the Schema Object definition with a unique name to improve output.