Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended practices for a more user-friendly API documentation.
Property
Value
Ruleset ID
openapi-v3-docsgen-linting
Code prefix
OPENAPI3DOCSGEN_L
Type
Linting
Default severity
Warning
Rule system
Semantic
Rules
32
Rules marked (disabled) are turned off by default, so they don't report issues.
The Info Object must specify details about the API using the description property. The value of the description must be non-null and non-empty.
OPENAPI3DOCSGEN_L053
required-info-contact
Warning
The Info Object must specify contact information using the contact property. This information helps users who may be stuck using your API e.g. you can include contact details of your support team that your API consumers can reach out to.
The description provides additional details or context about the environment. The environment object within the server configuration object should include a description.
OPENAPI3DOCSGEN_L151
server-description-exists
Information
The description property in the Server object provides a description of the server. It should not be missing or empty. The description helps API users understand the purpose and context of the server. Providing a description is an essential part of API documentation and helps to communicate the server's functionality to developers. A missing or empty description property can lead to confusion and ambiguity in the API documentation, making it difficult for developers to understand the API's intended purpose.
OPENAPI3DOCSGEN_L152
server-variable-description-exists
Information
In an OpenAPI specification, the Server Variable Object describes the value of an individual variable within a specific Server Object. This rule ensures that the Server Variable Object includes a non-empty description property, which is essential to describe the purpose of the variable.
OPENAPI3DOCSGEN_L153
server-parameter-description-exists
Information
The description provides additional details or context about the parameter used in the Server configuration. The Server Parameter should include a description.
The OpenAPI specification requires that every Path Item object includes a summary and/or description property. These properties provide a brief overview of the operations defined by the path.
The Operation Object must specify details about the operation using either the summary or the description property. The value of the summary/description must be non-null and non-empty.
The Parameter Object must specify details about the parameter using the description property. The value of the description must be non-null and non-empty.
OPENAPI3DOCSGEN_L381
parameter-example-or-examples-exist
Information
Parameter Object must specify a non-null, non-empty example value using either the example or examples property.
OPENAPI3DOCSGEN_L382
valid-parameter-example
Warning
The example value specified for the Parameter Object using either the example property or examples must be valid for the schema definition provided for that parameter.
OPENAPI3DOCSGEN_L385
non-empty-parameter-examples-key
Warning
The example name/key in the parameter level examples object is used to uniquely define an example value. Therefore, it should not be empty.
In an OpenAPI specification, the requestBody object defines the body of an HTTP request that an API client sends to the server. This rule ensures that the requestBody object must contain a description property that provides a clear and concise description of the request body.
The Response Object must specify details about the response using the description property. The value of the description must be non-null and non-empty.
Example Object must have a non-null and non-empty description or summary.
OPENAPI3DOCSGEN_L592
example-value-or-external-value-present
Warning
Example Value represents the actual example value, while External Value is used to reference an external file or URL containing the example. Each example object should include either an Example Value or an External Value.
OPENAPI3DOCSGEN_L593
valid-example-value
Warning
Examples within parameters or request body media types should not contain any properties marked as readOnly. Similarly, when providing examples for response object media types, it is important to avoid including any properties marked as writeOnly.
Every header object in an OpenAPI specification must include a description property that provides a brief explanation of the header's purpose.
OPENAPI3DOCSGEN_L661
header-example-or-examples-exist
Information
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.
OPENAPI3DOCSGEN_L662
valid-header-example
Warning
Example value provided for the header object should conform to the header schema.
OPENAPI3DOCSGEN_L664
non-empty-header-examples-key
Warning
The example name/key in header object level examples object is used to uniquely define an example value. Therefore, it should not be empty.
The Schema Object must specify details about the schema or the type of data it represents, using the description property. The value of the description must be non-null and non-empty.
OPENAPI3DOCSGEN_L753
schema-example-or-default-value-exists
Information
Schema Object must specify a non-null, non-empty example value using the example property or a default value using the default property if applicable.
OPENAPI3DOCSGEN_L755
valid-schema-example
Warning
The example value specified for the Schema Object using the example property must be valid for the type definition of that schema.
OPENAPI3DOCSGEN_L757
schema-example-equal-to-default-is-redundant
Warning (disabled)
Don't need to define an example if it’s exactly the same as your default value.
