OpenAPI support

We both support OpenAPI 2 (Swagger) and 3, but sometimes with specificities.

Adding topics to your documentation

Creating a good API documentation requires to give users context and guides. As OpenAPI doesn't permit to add generic content, we have created a custom property. Setting the x-topics property at the root of your documentation specification will let you add some content sections at the beginning of your documentation.

Each topic can have the following properties:

Property

Description

title

Topic title as it will appear in the navigation bar and in the content section.

content

The topic content. Markdown is fully supported here.

example

Will appear in the examples section, if activated. Markdown is fully supported here.

Example:

x-topics:
- title: Getting started
content: Before using the API you need yo get an API key by sending us an email.
- title: Authentication
content: Send the `X-API-KEY` header with all your requests.
example:
```
$ curl \
-X POST https://api.example.com/endpoint/ \
-H "X-API-KEY: XXXXXX" \
```

Not (yet) supported properties

securityShemes (V3)

OpenAPI V3 securitySchemes property is not supported yet. At the moment, if you want to describe your security layer, you can use our custom x-topics property.

securityDefinitions (V2)

We support OpenAPI V2 securityDefinitions property for these values:

  • basic

  • apiKey

We do not support oauth2, and won't in a near future. To describe an Oauth security definition, please use the x-topics property.

allOf

We do not support allOf statement at the moment, but we will. allOf attributes are fully ignored, and should be replaced by the merged properties.

anyOf

We do not support anyOf statement, and won't in a near future. Introducing anyOf would imply to support kind of a "or" statement, which is particularly complex to handle and restitute from an UI point of view.