The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174. [1]

Figure. 1. OpenAPI SpecificationVersion 3.0.3

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.[2]

Format

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

For example, if a field has an array value, the JSON array representation will be used: { "field": [ 1, 2, 3 ] }

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.

Patterned fields MUST have unique names within the containing object.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

• Tags MUST be limited to those allowed by the JSON Schema ruleset.
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Changing the OpenAPI version

By default, when the document is generated, the OpenAPI version used will be 3.0.3. If you use a static file as mentioned above, the version in the file will be used. You can also define the version in SmallRye using the following configuration:[3] mp.openapi.extensions.smallrye.openapi=3.0.2

References:

1. https://spec.openapis.org/oas/v3.0.3
2. https://swagger.io/specification/
3. https://quarkus.io/guides/openapi-swaggerui#changing-the-openapi-version

Cite this article:

Nithyasri S (2022), OpenAPI Specification Version 3.0.3 , Anatechmaz. pp.53