Generate an OpenAPI repository

This guide describes how to use the OpenAPI target to automatically generate and maintain a Git repository containing your OpenAPI specification and its variants.

Many teams maintain a public OpenAPI repository separate from their internal monorepo to:

• Provide a stable, public URL for their API specification
• Track and communicate API changes through Git history and commit messages
• Accept community contributions and bug reports via GitHub issues
• Integrate with documentation sites that reference the spec via raw.githubusercontent.com

Previously, teams had to manually configure CI/CD pipelines to push generated specs to a separate repository. The OpenAPI target automates this workflow and runs on every Stainless build.

Getting started

Enable the OpenAPI target

In the Studio, add openapi to your project’s targets:

targets:
  openapi:
    production_repo: null

This will create a repository at stainless-sdks/<project>-openapi with your OpenAPI specification.

Generated files

By default, the OpenAPI target generates the following files based on your configuration:

• openapi.json or openapi.yml - Your base input specification
• openapi.with-transforms.yml - Generated when openapi.transforms are configured (learn more about Stainless Transforms)
• openapi.with-code-samples.yml - Generated when openapi.code_samples are configured, adding SDK usage examples under x-codeSamples

The specific files generated depend on your Stainless configuration. If you haven’t configured transforms or code samples, only the base specification file will be generated.

Link a production repository

Once you’re ready to make your OpenAPI specification public, set up a production repository under your own organization:

1. Create a new empty repository in your organization (e.g., my-org/petstore-openapi)
2. Install the Stainless GitHub App and grant it access to this repository (see linking production repos for detailed instructions)
3. Update your Stainless configuration:

targets:
  openapi:
    production_repo: my-org/petstore-openapi

4. On your next build, Stainless will automatically push your OpenAPI specification to this repository

Customizing output files

Use targets.openapi.options.files to control exactly which files are generated and what they include:

targets:
  openapi:
    production_repo: my-org/petstore-openapi
    options:
      files:
        openapi.yml:
          with: []
        openapi.with-code-samples-and-transforms.yml:
          with: [code-samples, transforms]

Each key under files is the output filename, and the with array specifies which features to include:

• code-samples - Include SDK usage examples under x-codeSamples
• transforms - Include Stainless Transforms applied to your specification

Pro tip: If you’re using Stainless AI commit messages, these will automatically be included in your OpenAPI repository’s commit history, making it even easier to communicate changes to your API consumers.

Next Steps

If you find a bug, have a question, or want to provide product feedback, let us know at support@stainless.com.