Upgrade from Swagger 2.0 to OpenAPI 3.0

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. 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 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 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:

npm install -g swagger2openapi

Convert your specification

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

swagger2openapi ./swagger.json > openapi.json

Or if your specification is in YAML format:

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.

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