Bump.sh

Bump.sh helps you create a single source of truth for your APIs by documenting and cataloging changes across OpenAPI, AsyncAPI, Swagger, and more.

With the Stainless <> Bump 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.

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 Bump.sh 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.

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: 'bump.sh'

This tells Stainless to create a copy of your OpenAPI file extended with SDK code examples, in a format Bump.sh 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.

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. Connect Stainless with Bump.sh

The most efficient way to keep your SDK in sync with your documentation is through CI/CD automation. Stainless provides a GitHub Action to simplify that process:

# File .github/workflows/ci.yml

name: Upload OpenAPI spec to Stainless and Bump.sh

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - main

  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

jobs:
  update-docs:
    if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Push spec file to Stainless
        uses: stainless-api/upload-openapi-spec-action@main
        with:
          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
          project_name: <your-stainless-project-name>
          # Note: this should be the path to your specification file
          input_path: 'path/to/my-company-openapi.json'
          # Note: this file will be your spec extended with code samples
          output_path: './openapi-with-code-samples.json'

      - name: Deploy API docs to Bump.sh
        uses: bump-sh/github-action@v1
        with:
          doc: <your-bump-doc-id>
          token: ${{secrets.BUMP_TOKEN}}
          # Note: be sure this is pointing to the extended spec file
          file: './openapi-with-code-samples.json'

api-diff:
  if: ${{ github.event_name == 'pull_request' }}
  name: Check API diff with Bump.sh
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Comment pull request with API diff
      uses: bump-sh/github-action@v1
      with:
        doc: <your-bump-doc-id>
        token: ${{secrets.BUMP_TOKEN}}
        # Note: this should be the path to your specification file
        file: 'path/to/my-company-openapi.json'
        command: diff
      env:
        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

This workflow will do two things:

1. Whenever a Pull Request is created or updated, Bump.sh will generate a diff and submit a PR comment
2. When commits are pushed to your main branch, your OpenAPI spec file is uploaded to Stainless, triggering a new update to your SDKs. And a copy of your specification file extended with code samples is submitted to Bump.sh, to ensure your docs are in sync.

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