---
title: Upgrade from Swagger 2.0 to OpenAPI 3.0 | Stainless docs
description: Learn how to convert your Swagger 2.0 specification to OpenAPI 3.0 for use with Stainless.
---

Stainless requires an OpenAPI 3.0+ specification to generate SDKs. While Stainless doesn’t directly support Swagger 2.0, there are several ways to upgrade your Swagger 2.0 specification to OpenAPI 3.0+.

## Using the Stainless GitHub Action (Recommended)

If your Swagger 2.0 specification is stored in a GitHub repository, the recommended approach is to use the [Stainless Prepare OpenAPI Spec GitHub Action](https://github.com/stainless-api/upload-openapi-spec-action). This action integrates seamlessly with the Stainless ecosystem and can automatically convert and upload your specification whenever it changes.

Create a new workflow file at `.github/workflows/convert-swagger.yml` in your repository:

```
name: Convert Swagger to OpenAPI


on:
  pull_request:
    paths:
      - 'swagger.json'
      - 'swagger.yaml'
  push:
    branches:
      - main
    paths:
      - 'swagger.json'
      - 'swagger.yaml'


permissions:
  contents: write
  pull-requests: write


jobs:
  convert-swagger:
    runs-on: ubuntu-latest


    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref || github.ref }}
          token: ${{ secrets.GITHUB_TOKEN }}


      - name: Convert Swagger to OpenAPI
        uses: stainless-api/upload-openapi-spec-action/prepare/swagger@v1
        with:
          # Path to your Swagger 2.0 spec file
          input_path: ./swagger.json


          # Path where the converted OpenAPI 3.x spec will be written
          output_path: ./openapi.json


          # Fix up small errors in the source definition
          patch: false


          # Resolve external references
          resolve: true


          # Target OpenAPI version: '3.0' or '3.1'
          target_version: '3.0'


          # Whether to commit the converted file
          commit: true


          # Commit message (only used if commit is true)
          commit_message: 'chore: convert Swagger 2.0 to OpenAPI 3.x'


          # GitHub token for committing
          github_token: ${{ secrets.GITHUB_TOKEN }}
```

This workflow will:

1. Trigger whenever your Swagger file is modified in a pull request or pushed to main
2. Check out the code from the appropriate branch
3. Convert your Swagger 2.0 file to OpenAPI 3.x format
4. Automatically commit the updated OpenAPI file back to the repository

This action uses `swagger2openapi` under the hood and provides additional integration with Stainless workflows. You can combine it with the [Stainless Import OpenAPI Spec GitHub Action](https://github.com/stainless-api/upload-openapi-spec-action/blob/main/examples/prepare_swagger.yml) to automatically upload your converted specification to Stainless.

### Configuration options

The Stainless GitHub Action supports several configuration options:

- **`input_path`** (required): Path to your Swagger 2.0 spec file (JSON or YAML)
- **`output_path`** (optional): Where to write the converted file. Defaults to `openapi.json` in the same directory
- **`patch`** (optional): Fix up small errors in the source definition. Default: `false`
- **`resolve`** (optional): Resolve external references. Default: `true`
- **`target_version`** (optional): Target OpenAPI version (`3.0` or `3.1`). Default: `3.0`
- **`commit`** (optional): Whether to commit the converted file. Default: `false`
- **`commit_message`** (optional): Custom commit message when committing changes
- **`github_token`** (optional): GitHub token for committing. Defaults to `GITHUB_TOKEN`

## Using `swagger2openapi` CLI

For local development or if your specification isn’t in GitHub, you can use the [`swagger2openapi`](https://www.npmjs.com/package/swagger2openapi) CLI tool directly. This Node.js package can convert your Swagger 2.0 JSON or YAML files to OpenAPI 3.0 format.

### Install swagger2openapi

Install `swagger2openapi` globally using npm:

Terminal window

```
npm install -g swagger2openapi
```

### Convert your specification

Once installed, you can convert your Swagger 2.0 file to OpenAPI 3.0:

Terminal window

```
swagger2openapi ./swagger.json > openapi.json
```

Or if your specification is in YAML format:

Terminal window

```
swagger2openapi ./swagger.yaml > openapi.yaml
```

The `swagger2openapi` tool attempts to preserve as much information as possible during conversion, but you should review the generated OpenAPI 3.0 specification to ensure accuracy, especially for complex schemas or edge cases.

## Other conversion options

While `swagger2openapi` is the most popular tool, there are other options available:

- **Online converters**: Various web-based tools can convert Swagger 2.0 to OpenAPI 3.0, though they may have limitations for large or complex specifications.
- **Manual conversion**: For simple specifications, you can manually convert following the [OpenAPI 3.0 migration guide](https://swagger.io/docs/specification/migrating-to-3-0/).

## Next steps

Once you have an OpenAPI 3.0 specification:

1. **Upload your OpenAPI spec to Stainless**: Upload directly or provide a public url. Use the [Stainless Import OpenAPI Spec GitHub Action](https://github.com/stainless-api/upload-openapi-spec-action) to upload your OpenAPI 3.0 specification to Stainless.

2. **Review generated SDKs**: After your first build, review the generated SDKs to ensure everything converted correctly. Pay special attention to:

   - Request/response schemas
   - Authentication methods
   - Parameter types and formats
   - Error responses