Skip to main content

ReadMe

ReadMe is a documentation platform that helps you create and maintain documentation for your APIs.

With the Stainless <> ReadMe integration, you can:

  1. Generate robust and polished SDKs directly from your OpenAPI spec.
  2. Inject code samples into API docs, providing developers with language-specific implementation examples.
  3. Keep docs and SDKs automatically in sync as your API evolves.

JavaScript code example rendered by ReadMe API docs

This integration bridges the gap between documentation and implementation, giving developers copy-paste-ready examples that demonstrate your API in action.

Prerequisites​

Before starting, make sure you have:

  • An account on Stainless
  • An existing ReadMe documentation project
  • Your OpenAPI specification

1. Create Your SDKs in the Studio​

  1. Log in to the Stainless dashboard
  2. Click "New Project" and upload your OpenAPI specification
  3. Stainless will analyze your API and create an initial SDK configuration

The SDK Studio provides an immediate preview of your SDK structure based on your API's resources, methods, and models.

Stainless SDK Studio showing SDK preview

When first created, Stainless organizes your API into logical resources, but the exact names and hierarchy is up to you, allowing you to create the most intuitive experience for your users.

The Studio lets you customize everything from resource naming to authentication schemes - dive into the configuration guide to learn how to prepare SDKs developers will love.

2. Generate Code Examples​

In the Studio, add the following to your Stainless configuration file:

openapi:
  code_samples: 'readme'

This tells Stainless to create a copy of your OpenAPI file extended with SDK code examples, in a format ReadMe can render. For advanced integration options and support for other documentation platforms, explore the documentation integration guide.

3. Create a Stainless API key​

Go to your Stainless org page, select the "API Keys" tab, and create a new key.

Form to create an API key to use Stainless API

Note: the API key should be considered secret and will only be shown once, be sure to copy and store it to a safe location, such as a password manager.

You can now navigate to the GitHub repository where your OpenAPI spec is located, and add a GitHub secret named STAINLESS_API_KEY, with the API key as value.

4. Publish the URL to your OpenAPI spec​

Go to your Stainless project page, select the "Release" tab, and select "Setup OpenAPI publishing."

Publishing your documented OpenAPI spec

Turn the OpenAPI publishing toggle on. This will create a stable publicly accessible URL for your OpenAPI spec which can be used by ReadMe. This OpenAPI spec is enriched with Stainless SDK code samples in the x-code-samples field.

The URL is stable and will always stay up-to-date with the latest information about your SDKs.

Finally, click the "copy" button next to the URL. Now you can use this URL when adding an API definition to your ReadMe project.

By combining Stainless's SDK generation with ReadMe's documentation capabilities, you're providing developers with a seamless experience from discovery to implementation.