Skip to main content

Integrate with docs frameworks

Stainless can output code snippets which are read by API reference documentation providers to be displayed on the documentation website.

The snippets demonstrate how to make each request with the user's chosen SDK (for example, show client.items.list() instead of curl https://api.my-company.com/items). This provides an easy, copy-and-pasteable snippet for your users to hit the ground running for any API call.

Setup OpenAPI decoration​

We officially support integrations with Readme, Mintlify, and Redocly, but any API docs provider can render these examples as long as they support the relevant OpenAPI extension. To export snippets, you first have to add the openapi.code_samples key to your Stainless config.

This tells the Stainless generator to generate snippets in a format your docs provider understands.

We currently generate snippets for Node, Python, and Go.

stainless.yml
openapi:
  code_samples: 'readme'

Upload OpenAPI spec to provider​

You now have to forward your OpenAPI spec (decorated with code snippets) to your docs provider:

Option 1: GitHub Action​

The decorated OpenAPI spec can be retrieved as output when you use the Stainless GitHub action for pushing an updated OpenAPI spec to Stainless.

You can use the same GitHub workflow to copy the decorated spec to your API docs provider to ensure API docs always stay in sync with your SDKs.

The integration with some docs providers is easier with a persistent link. We can expose a publicly-viewable persistent link to a decorated spec which gets automatically updated with new changes (beta, contact us).

Stainless generates SDK code snippets in Node and Python (more languages coming soon). The code snippets are additionally viewable in the SDK Reference Preview tab in the SDK Studio for preview.