Advanced Features
Support for advanced OpenAPI features
OpenAPI 3 has some advanced features for describing complex APIs. Here’s how you can use them with Docuo.
oneOf, anyOf, allOf
For complex datatypes, OpenAPI provides the oneOf, anyOf, and allOf keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the Swagger documentation, but essentially:
oneOffunctions like an “exclusive-or” operatoranyOffunctions like an “or” operatorallOffunctions like an “and” operator
Docuo treats the oneOf and anyOf keywords the same. We have found that, when people use oneOf, they often mean anyOf - and there is often no meaningful difference to the user.
Docuo performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with allOf, Docuo combines the properties of both into a single object. When you combine two schemas with anyOf or oneOf, Docuo displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a unique title field.
Docuo currently does not support the not keyword.
x-codeSamples
If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Docuo will display them in your OpenAPI pages. You can define your code samples using the x-codeSamples extension described in Redocly’s documentation. This property can be added within any request method, and has the following schema:
lang string required
The language of the code sample.
label string
The label for the sample. This is useful when providing multiple examples for a single endpoint.
source string required
The source code of the sample.
Here’s an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
paths:
/plants:
get:
...
x-codeSamples:
- lang: bash
label: List all unwatered plants
source: |
planter list -u
- lang: javascript
label: List all unwatered plants
source: |
const planter = require('planter');
planter.list({ unwatered: true });
- lang: bash
label: List all potted plants
source: |
planter list -p
- lang: javascript
label: List all potted plants
source: |
const planter = require('planter');
planter.list({ potted: true });