-
Notifications
You must be signed in to change notification settings - Fork 215
Update the Stainless integration process #706
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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."> | ||
ethanpalm marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| 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> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.