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.