OpenAPI

OpenAPI is fully supported.

The Stainless OpenAPI target automatically generates and maintains a Git repository containing your OpenAPI specification and its variants. This makes it easy to provide a stable, public URL for your API specification and track changes through Git history.

Considerations

An OpenAPI repository gives your users a stable, public location to access your API specification and track changes over time. This is particularly valuable if you:

• Need to provide a consistent URL for your API specification that documentation sites can reference
• Want to communicate API changes through Git commit messages and diffs
• Want to accept bug reports and contributions from the community via GitHub issues and pull requests
• Are using features like Stainless Transforms or code samples that you want to publish alongside your base specification

The OpenAPI target automates the workflow of pushing generated specs to a separate repository on every Stainless build.

Configuration

To generate an OpenAPI repository, add the openapi target to your Stainless configuration file:

targets:
  openapi:
    production_repo: my-org/petstore-openapi
    edition: openapi.2025-10-08

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

For a complete list of configuration options, see the OpenAPI target reference.

Customizing output files

By default, the OpenAPI target generates 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.

You can 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

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

Editions

Editions allow Stainless to make improvements to SDKs that aren’t backwards-compatible. You can explicitly opt in to new editions when you’re ready. See the SDK and config editions reference for more information.

openapi.2025-10-08

• Initial edition for OpenAPI (used by default if no edition is specified)

Publishing

Stainless automatically pushes your OpenAPI specification to your production repository on every build. No additional setup is required beyond linking the repository.

You need to link a production repository where Stainless will push your OpenAPI specification.