OpenAPI Code Sample Tag Redocly Custom Tag
The openapi-code-sample
tag renders sample code snippets directly in your documentation, showing users how to interact with API operations defined in your OpenAPI description.
Syntax and usage
To use the tag, pass the filepath of your OpenAPI description using the descriptionFile
attribute and a reference to the specific operation using either operationId
or pointer
. You can also use additional attributes to configure the code sample element rendered in the document.
With operationId
:
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
operationId="getMuseumHours"
/%}
With pointer
:
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
pointer="/paths/~1museum-hours/get"
/%}
Attributes
Attribute | Type | Description |
---|---|---|
descriptionFile | String | REQUIRED. A path to an OpenAPI description. |
operationId | String | ID of the operation inside the OpenAPI description. Required if pointer is not specified. |
pointer | String | Pointer to an operation inside the OpenAPI description. Required if operationId is not specified. Slashes used on endpoints must be encoded with ~1 -- for example, /paths/~1some-endpoint/post . |
exampleKey | String | Key specifying which example to use. Must match the key used for an operation's example in the OpenAPI description. |
language | String | Limits the code sample to a specific language. Works with the following values (case sensitive): Payload, curl, C#, Node.js, JavaScript, Python, R, Ruby, PHP, Go, Java. |
parameters | Object | Custom parameters to use for the OpenAPI operation code sample. Accepts values for header and query . |
requestBody | Object | Defines an inline request body to use. Replaces any request body in the code sample. |
environment | String | Limits the environment picker in the code sample to a specific server defined in the OpenAPI description. |
environments | Object | Provide environment variables that resolve to your code sample. Variables are based on your OpenAPI description's securitySchemes . See environment variables. |
Environment variables
The environment variables available in the code sample correspond with your security schemes. The name of the security scheme must be used in the variable. Here's a list of available variables:
- Basic auth =
SchemeName_username
andSchemeName_password
- JWT token or OAuth token =
SchemeName_token
- OAuth credentials =
SchemeName_client_id
andSchemeName_client_secret
- API key auth does not have a suffix, so the variable is
SchemeName
By prefilling security credentials for logged in users, you can provide code samples that are fully ready to execute.
For example:
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
operationId="createSpecialEvent"
environment="https://api.fake-museum-example.com/v1"
environments={
"https://api.fake-museum-example.com/v1": {
"MuseumOAuth_token": $user-props.token,
}
}
/%}
Examples
Basic usage
By default, the tag will render a code sample in multiple languages for a specific API operation, as in the following example:
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
operationId="createSpecialEvent"
/%}
- https://api.fake-museum-example.com/v1.1
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \ -u <username>:<password> \ https://api.fake-museum-example.com/v1.1/special-events \ -H 'Content-Type: application/json' \ -d '{ "name": "Mermaid Treasure Identification and Analysis", "location": "Under the seaaa 🦀 🎶 🌊.", "eventDescription": "Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.", "dates": [ "2023-09-05", "2023-09-08" ], "price": 0 }'
With single language
You can restrict the code sample to a specific language using the language
attribute. The following example limits the code sample to JavaScript:
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
operationId="createSpecialEvent"
language="JavaScript"
/%}
- https://api.fake-museum-example.com/v1.1
const resp = await fetch( `https://api.fake-museum-example.com/v1.1/special-events`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Basic ' + btoa('<username>:<password>') }, body: JSON.stringify({ name: 'Mermaid Treasure Identification and Analysis', location: 'Under the seaaa 🦀 🎶 🌊.', eventDescription: 'Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.', dates: [ '2023-09-05', '2023-09-08' ], price: 0 }) } ); const data = await resp.json(); console.log(data);
With pre-defined values
You can use various attributes to provide values that resolve to the rendered element. The following example includes pre-defined parameters and environment variables.
{% openapi-code-sample
descriptionFile="../../openapi/museum-api.yaml"
operationId="deleteSpecialEvent"
language="curl"
parameters={
path: {
eventId: "dad4bce8-f5cb-4078-a211-995864315e39"
}
}
environment="https://api.fake-museum-example.com/v1"
environments={
"https://api.fake-museum-example.com/v1": {
"MuseumPlaceholderAuth_username": "custom-username",
"MuseumPlaceholderAuth_password": "custom-password"
}
}
/%}
- https://api.fake-museum-example.com/v1.1
curl -i -X DELETE \ -u custom-username:custom-password \ https://api.fake-museum-example.com/v1.1/special-events/dad4bce8-f5cb-4078-a211-995864315e39
Best practices
Customize for flexibility
The various attributes give you a lot of flexibility to customize the code sample, allowing you to meet a more diverse range of API scenarios. You can use them to tailor the code samples to the specific needs of your users.
Document code samples
Code samples should be paired with comprehensive documentation. You should explain the purpose of each sample, the expected behavior, and any modifications that users might need to make. This will help users more successfully build with your API.