OpenAPI format requirements

OpenAPI Specification (formerly known as Swagger specification) is the industry standard for specification and documentation of REST APIs. A valid and detailed OpenAPI file serves as the contract between the API provider and API consumers. This contract also helps security tools audit your API for security, test live endpoints for conformance to the contract set out in the API definition, and protect the endpoint at runtime.

Ensure that your API contract meets OpenAPI requirements before using it with other tools and consumers. This section helps you get your OpenAPI definition aligned with the OpenAPI Specification (OAS).

Format issues can be divided into three categories:

• Structure: Structural issues in the API definition, like wrong type of values, required properties not defined, or properties defined in wrong places.
• Semantics: Issues in the contents of the API definition so that the values of parameters do not make sense
• Best practices: Issues that cause the API definition to deviate from the best practices and the spirit of the OAS, like not defining recommended response types for operations.