OpenAPI Specification (OAS)

Formerly known as Swagger specification, the OAS has emerged as a widely adopted way of documenting REST APIs. It offers a standard format with large tooling support. Instead of trying to deduce the intent of an API from its behavior or source code, the standard OpenAPI contract makes it easier to communicate this clearly.

One of the key functions that the standard contract can enable is API security, because it provides a way for developers, operations, and security people across teams to speak in common language. When all teams building both the API and the infrastructure the API is going to sit in can clearly communicate the intent, requirements, and outcome, it is also easier and more reliable to uncover, understand, and mitigate security risks. This idea is in the core of 42Crunch Platform.

The OAS allows to clearly specify a contract, the terms and conditions of using the API and the functions it offers. This contract takes the form of an OpenAPI definition, which describes among other things:

  • The functions (operations) that the API offers
  • The data that the API requires or accepts as input for each function
  • The data that the API returns as a response to calling a particular function
  • The security measures protecting the API
  • The linking and connections that the API has to other APIs

The OAS enables developing and utilizing various tools throughout your API's life cycle, such as:

  • Automatically generated API documentation
  • Testing tools
  • Code generation tools for generating servers and clients
  • API firewalls and firewall rules to protect API infrastructure

The OAS does not require completely rewriting your existing APIs, or binding any software to your service. You simply describe the capabilities of the service as the OAS specifies.

OAS versions

There are currently three versions of the OAS that have significant differences between them:

  • Version 2
  • Version 3.0.x
  • Version 3.1.x

The following table summarises some of the key differences between the OAS v2 and v3.0.x:

Feature OAS v2 OAS v3.0.x
Specification and versioning
  • Specification version defined in swagger
  • Specification version defined in openapi
URLs
  • URLs compiled from host, basePath, and schemes
  • Only one API endpoint URL, multiple schemes allowed
  • URLs defined in a dedicated url object
  • Multiple URLs allowed
Paths and methods
  • GET and DELETE can take a request body
  • TRACE not supported
  • Request body no longer allowed for GET and DELETE
  • TRACE supported
Object definitions
  • Parameters and response headers can be defined as object in their own right
  • Cookie parameters not supported
  • MIME types defined in consumes and produces
  • Parameters and response headers must be defined with schemas
  • Cookie parameters supported
  • body and formData replaced by requestBody
  • consumes and produces replaced by content, support for wildcards for mediatypes
  • Support for content type negotiation
  • Callbacks and links as new object types
Combining operations and additional properties
  • oneOf and anyOf not supported
  • additionalProperties as Boolean not supported
  • All combining operations supported
  • additionalProperties as Boolean supported
  • additionalProperties defaults to true, must be explicitly declared as false if a schema must not accept additional properties
Reusable objects
  • Defined under definitions
  • Limited range of reusable components
  • Defined under components
  • More types of reusable components
Security
  • Security schemes defined under securityDefinitions
  • OIDC not supported
  • Cookie authentication not supported
  • securityDefinitions removed
  • OIDC supported
  • Cookie authentication supported
  • Renamed and restructured OAuth2 flows
  • basic renamed to http
Examples
  • Only JSON or YAML objects supported
  • In addition to JSON or YAML objects, examples can also be described as JSON strings
  • Reusable examples object

The following table summarises some of the key differences between the OAS v3.0.x and v3.1.x:

Feature OAS v3.0.x OAS v3.1.x
Specification and versioning
  • Semantic versioning
  • Focused on REST APIs
  • Semantic versioning dropped
  • $schema keyword at the root of the API definition allows specifying the meta-schema for validating the OAS
Webhooks
  • Webhooks not natively supported
  • Paths mandatory
  • Support for webhooks
  • Paths optional if webhooks used
Object definitions
  • Improved but partial or modified JSON Schema support
    • Object type null not supported, the property nullable as a workaround
    • type cannot be an array
    • Properties cannot appear alongside $ref
  • Full support for JSON Schema Draft 2020-12
    • Object type null supported, nullable deprecated
    • Support for arrays in type
    • Other properties can be defined alongside $ref
    • Support for $defs for reusable schema definitions
Combining operations and additional properties
  • Problems with additionalProperties behavior in composition
    • additionalProperties: false can conflict with composition using combining operations
    • additionalProperties: true allows any additional properties
  • Improved composition
    • unevaluatedProperties excludes properties not defined in any of the subschemas composing the final object, works seamlessly with combining operations
Security
  • mTLS not natively supported
    • x-42c-mtls as a workaround
  • Only OAuth 2.0 schemes allow more granular authorization through scopes
  • mTLS supported
    • x-42c-mtls must not be used
  • All security requirements support defining an array of required roles for more granular authorization
Examples
  • examples object for reusable examples
  • Singular example keyword for providing individual examples
  • examples keyword for providing examples, can include arrays of multiple examples
  • Singular example keyword deprecated
  • #components/examples retained for reusable objects

Schema object definitions in the OAS are an extended subset of the JSON Schema Specification Wright Draft 00, and for the most part correspond to how JSON schemas are defined, with some exceptions. Two notable exceptions are that in JSON schema, you can define the property type as an array, often to allow for null properties, and null is a valid type. However, in the OAS, arrays in type or null as a type are not supported.

If you must allow for null properties, in the OAS v3, you can add the property nullable to your schema and set it to true.

The OAS v2 does not have the property nullable. Instead, as a workaround, you can add the OAS extension x‑nullable to your schema and set it to true. Some tooling, such as all features in 42Crunch Platform, support this workaround, but the support is not universal. Using x‑nullable together with required in your schemas can also cause problems. For proper support, we recommend switching from OAS v2 to OAS v3.

What is...

APIs and API collections

API Security Audit

GraphQL specification

How to...

Import APIs

Manage API collections

Audit API security