Skip to main content

OpenAPI support

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

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

  • http
  • apiKey
  • oauth2
  • openIdConnect

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

readOnly and writeOnly properties

JSON Schema provides possibility to declare a property as read or write Only, with boolean fields writeOnly and readOnly (cf OpenAPI 3.0.3 or JSON Schema documentation).

Basically, in REST API context, it means that a writeOnly property makes sense in request only (as password for example). Thus, we decided to hide a property defined as writeOnly when it belongs to a response.

And a readOnly makes sense in response only (as created_at, updated_at, your call...). Similarly, we decided to hide a property defined as readOnly when it belongs to a request body.

Thus, it becomes easy to use the same Schema Object in different contexts, for example as seen below:

"schema": {
"properties": {
"password": {
"type": "string",
"format": "password",
"writeOnly": true
},
"created_at": {
"type": "string",
"format": "date-time",
"readOnly": true
}
}
}

Add topics to your documentation

As this is not supported by OpenAPI, we created a custom property to enrich your documentation. Find out more in our dedicated section.