---
title: OpenAPI | Stainless
description: Generate and maintain a Git repository containing your OpenAPI specification and its variants
---

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](/docs/reference/config#openapi/index.md).

### 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](/docs/guides/transforms/index.md) about [Stainless Transforms](https://www.stainless.com/blog/stainless-transforms-the-fast-lane-for-fixing-imperfect-openapi-specs))
- `openapi.with-code-samples.yml` - Generated when `openapi.code_samples` are [configured](/docs/guides/integrate-docs#third-party-documentation-platforms/index.md), 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](/docs/guides/ai-commit-messages/index.md), 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](/docs/reference/editions/index.md) 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](/docs/guides/publish#link-production-repos/index.md) where Stainless will push your OpenAPI specification.