OpenAPI support

We support all major versions from Swagger (OpenAPI v2) to OpenAPI 3.2. This page describes some specificities related to our support for this specification.

Minimal mandatory fields #

Bump.sh needs to receive at least these fields to generate a REST documentation

field description
openapi or swagger define which version of the specification you want to use. Use the swagger key for v2 and openapi for the v3+. E.g. openapi: "3.2.0".
info General information about your API
info.title The title of the API
info.version The version of the API document

Partially supported: securitySchemes (V3) / securityDefinitions (V2) #

We support OpenAPI securitySchemes property (securityDefinitions with openAPI v2) with these authentication type values:

We do not support mutualTLS. To describe a mutualTLS authentication method, please use the x-topics property for now.

Partially supported: XML generated examples #

We currently generate request or response examples in both JSON and XML format if none are provided in your Schema object definitions. However we don’t yet support the xml: attribute on Schema objects.

readOnly and writeOnly properties #

JSON Schema provides the possibility to declare a property as read or write only. Read more in the JSON Schema section of this documentation.

Webhooks support #

You can use the webhooks field (introduced in OpenAPI 3.1) to define the API webhook payloads. Please read to the dedicated documentation page for more information.

Overlays support #

The Overlay specification of OpenAPI makes it possible to modify the content of an OpenAPI document by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original file. Please read to the dedicated documentation page for more information.

OpenAPI 3.2 #

OpenAPI 3.2 is fully supported. To use it, set the version in your API document:

openapi: "3.2.0"

The features introduced by this version are handled as follows:

Feature Bump.sh behaviour
QUERY method Rendered in the documentation and available in the API Explorer.
Tag Object: parent Builds a nested navigation. A tag used as a parent becomes a section of the navigation, and its child tags become the groups of operations it contains. This is the OpenAPI 3.2 equivalent of the x-tagGroups vendor extension.
Tag Object: kind Used to distinguish navigation tags (kind: nav) from other categorizations.
Tag Object: summary Used as the tag display name, behaving like our x-displayName vendor extension.
Server Object: name Displayed in the server selector.
Response Object: summary Displayed alongside the response.
Security Scheme Object: deprecated Displays a deprecation badge on the security scheme.

For a deeper walkthrough of tag hierarchies, see Grouping operations with tags.