Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added images/stainless-public-OpenAPI-spec.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
76 changes: 28 additions & 48 deletions integrations/sdks/stainless.mdx
Original file line number Diff line number Diff line change
@@ -1,52 +1,32 @@
---
title: Stainless
description: Automate your SDK example snippets in the API playground
description: Automate SDK example snippets in your API playground
---

If you use Mintlify's OpenAPI support for your API reference documentation, add the following to your Stainless config:

```yaml openapi.stainless.yml
openapi:
code_samples: mintlify
```
Configure the [OpenAPI setup](/api-playground/openapi/setup#in-the-repo) in your Mintlify docs. To integrate Stainless, modify the GitHub Action that uploads your OpenAPI spec to Stainless so that it pushes the Stainless-enhanced OpenAPI spec into your docs repo like so:
```yaml
name: Upload OpenAPI spec to Stainless and (Mintlify) docs repo

on:
push:
branches: [main]
workflow_dispatch:

jobs:
stainless:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Push spec and config to Stainless and outputs documented spec
uses: stainless-api/upload-openapi-spec-action@main
with:
input_path: 'path/to/my-company-openapi.json'
config_path: 'path/to/my-company.stainless.yaml'
output_path: 'path/to/my-company-openapi.documented.json'
project_name: 'my-stainless-project'
- name: Push documented spec to docs repo
uses: dmnemec/copy_file_to_another_repo_action@main
env:
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
with:
source_file: 'config/my-company-openapi.documented.json'
destination_repo: '{DOCS_REPO_NAME}'
destination_folder: 'openapi-specs' # (optional) the folder in the destination repository to place the file in, if not the root directory
user_email: '{EMAIL}' # the email associated with the GH token
user_name: '{USERNAME}' # the username associated with the GH token
commit_message: 'Auto-updates from Stainless'
```
This assumes the following secrets have been [uploaded to your GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
- `secrets.STAINLESS_API_KEY`: Your Stainless API key.
- `secrets.API_TOKEN_GITHUB`: A GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with permissions to push to your docs repo.
## Prerequisites

* Have a valid OpenAPI specification in your `docs.json`. See [OpenAPI Setup](/api-playground/openapi/setup) for more details.
* Have a [Stainless](https://app.stainless.com) account.

## Integrate with Stainless

<Steps>
<Step title="Set up OpenAPI decoration in Stainless.">
In your `stainless.yml` config file, add `openapi.code_samples: 'mintlify'`. See the [Stainless documentation](https://app.stainless.com/docs/guides/integrate-docs) for more information.
</Step>
<Step title="Get the URL to your OpenAPI spec.">
In your Stainless project:

1. Select the **Release** tab.
2. Select **Setup OpenAPI publishing**.
3. Copy the URL to your publicly accessible OpenAPI spec.

<img
src="/images/stainless-public-OpenAPI-spec.png"
alt="Stainless release page with the OpenAPI spec URL highlighted with a green box."
/>
</Step>
<Step title="Add your OpenAPI spec URL to your `docs.json`.">
In your `docs.json` file, add the URL from Stainless to the `openapi` field. See [OpenAPI Setup](/api-playground/openapi/setup) for more information.
</Step>
</Steps>