Skip to main content

no-inline-enum-schema-definition

Overview​

This rule belongs to the openapi-v3-apimatic-linting ruleset and states that:

Either define a title property alongside the enum property or the 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 aren't recommended as for autogenerating SDKs/documentation the names of such schemas are deduced from the parent objects in which they're 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.

PropertyValue
EnabledYes
Maximum SeverityWarning
MessageInline enum schema definition found.
CodeOPENAPI3APIMATIC_L692
TypeLinting
Rule SystemSemantic
Broad CategoryOpenAPI Schemas
Products ImpactedAPI Transformer, Code Generation, Developer Experience Portal
Tagsopenapi3 openapi apimatic semantic linting enum schema inline components

Suggested Fixes​

  • Add title property alongside the enum property in the schema definition.
  • 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 title property in the Schema Object definition with a unique name to improve output.

For More Information​