OpenAPI

Array Items.

Parameter must have examples.

example key must be snake cased (e.g. snake_case).

Message must have examples.

The API contract MUST include a 'securitySchemes' subsection under the 'components' section.

Contact object must have "name", "url" and "email".

Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`: `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control` and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234.

Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`: `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control` and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234.

The API should declare its servers so all hosts and environments are inventoried — undocumented or stray non-production hosts are a common inventory-management risk (OWASP API9).

The API contract MUST include a 'components' section.

Defining external documentation provides a link to detailed API guides, tutorials, and reference material beyond the OpenAPI spec. Analysis shows 57.1% of APIs include external docs.

openapi document should declare a `jsonSchemaDialect` property.

openapi document should declare a `openapi` property.

openapi document should declare a `paths` property.

API design SHOULD include real-like examples for request and response definitions.

Every OpenAPI should define at least one server URL. Analysis shows 97.2% of APIs define servers, providing consumers with the base URL needed to make requests.

openapi document should declare a `webhooks` property.

Spec should not be empty.

Enum values must not have duplicate entry.

All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation.

'HTTP' headers SHOULD NOT start with 'X-' RFC6648.

Headers must include examples.

Info object must have "contact" object.

Having a contact email address associated with the technical contract ensures that anyone who comes across the API has someone to email and get more information.

Having a contact name associated with the technical contract ensures that anyone who comes across the API knows who to contact.

Having a contact url associated with the technical contract ensures that anyone who comes across the API knows where to go to contact someone.

Info "description" must be present and non-empty string.

Having a restriction on the length of the API description expressed as the OpenAPI info description helps provide constraints for consumers when adding a description, and keeps portals, landing pages, documentation, and discovery results more consistent.

Eval functions MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.

Script tags MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.

Info object must have "license" object.

The license object should include a name property identifying the license type, such as Apache 2.0, MIT, or a proprietary license.

The license object should include a URL linking to the full license text so API consumers can review the terms.

x-microcks extension must be valid.

The API should declare a version in info.version so every published version is inventoried and retired versions can be tracked (OWASP API9 — improper inventory management).

The `#/info/x-api-id` field can be used to associate an identifier to an API. This is useful to track an API even when its `#/info/title` changes.

Having a contact object associated with the technical contract ensures that anyone who comes across the API has someone to contact and get more information.

Info section is missing a description.

Having a license defined in the info object clarifies the terms under which the API can be used. Analysis shows only 44.4% of APIs define a license, but it is essential for API governance and compliance.

APIs should use OpenAPI 3.x specification. Analysis of 773 API specs shows 97% use OpenAPI 3.x, with 86% on 3.1.0, making it the dominant standard for modern API definitions.

The `#/info/x-summary` can be used to specify a brief, one-liner description of your API: this is very useful for catalog purposes (eg. this can be shown as your API subtitle in catalogs and developer portals). In OAS3.1 you can use the standard `#/info/summary` field.

API MUST reference the URL of the Terms of Service in `#/info/termsOfService`.

Having a intuitive and helpful title for your API using the OpenAPI info title is the first impression you will make on the consumers of your API.

Publishing a version for your OpenAPI technical contract helps you communicate change with consumers using Semantic or date-based versioning published to the info version property.

Having a consistent casing for the title for your API helps provide constraints for teams naming the API, but also keep consistent with other APIs from across teams.

Having a limitation on the length of the title for your API helps provide constraints for teams naming it, but also keep consistent with other APIs from across teams.

The API version field should follow [semantic versioning](https://semver.org/#semantic-versioning-specification-semver).

Version should use semantic versioning. {{value}} is not a valid version.

The API contract MUST have a stable version and MUST follow semantic versioning (e.g., '1.0.0'). Words like 'SNAPSHOT' or 'RELEASE' are not allowed.

License object must include "url".

The hierarchy of nested resources SHOULD NOT contain more than 8 resource names in the path.

APIs SHOULD NOT expand their total URL length beyond a few hundred characters.

The URL path should not contain more than 3 dynamic path parameters.

Message example must match params examples to form full mocks.

Message must have examples.

Property must not be placed among $ref.

Markdown descriptions must not have "eval(".

Markdown descriptions must not have "