Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Linting for APIMatic Portal Generation
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.
OpenAPI Info
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L050 | info-description-exists | Information | 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. |
OpenAPI Servers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L150 | environment-description-exists | Information | 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. |
OpenAPI Path Items
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L240 | path-item-summary-or-description-exists | Information (disabled) | 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. |
OpenAPI Operations
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L300 | operation-summary-or-description-exists | Information | 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. |
OpenAPI Parameters
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L380 | parameter-description-exists | Information | 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. |
OpenAPI Request Body
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L430 | request-body-description-exists | Information | 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. |
OpenAPI Media Types
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L460 | mediaType-example-or-examples-exist | Information | Media Type Object must specify a non-null, non-empty example value using either the example or examples property. |
OPENAPI3DOCSGEN_L461 | valid-media-type-example | Warning | The example value specified for a Media Type Object using either the example property or examples must be valid for the given schema definition. |
OPENAPI3DOCSGEN_L463 | non-empty-media-type-examples-key | Warning | The example name/key in media type level examples object is used to uniquely define an example value. Therefore, it should not be empty. |
OpenAPI Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L520 | response-description-exists | Information | 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. |
OpenAPI Examples
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L590 | example-summary-or-description-exists | Information | 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. |
OpenAPI Headers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L660 | header-description-exists | Information | 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. |
OpenAPI Tags
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L710 | tag-description-exists | Information | Tag Object must have a non-null non-empty description. |
OpenAPI Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L750 | schema-description-exists | Information | 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. |
OpenAPI Security Schemes
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L840 | security-scheme-description-exists | Information | Security Scheme Object should have a non-null and non-empty description. |
OPENAPI3DOCSGEN_L841 | additional-header-description-exists | Information | Additional header should have a non-null and non-empty description. |
OpenAPI OAuth 2.0 Flows
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3DOCSGEN_L870 | non-empty-oauth-flow-scope-description | Information | OAuthFlow object should have a non-null and non-empty scope vaule. |
Learn more
OpenAPI v3 Syntax Linting for APIMatic Code Generation
Linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended syntax practices for better code generation experience.
OpenAPI v3 Syntax Linting for APIMatic Portal Generation
Syntax linting checks performed by APIMatic on provided OpenAPI v3 file to check its conformance to recommended practices for a more user-friendly API documentation.