Automatically Upgrade to OpenAPI v3.2

Upgrade old OpenAPI/Swagger documents to the latest and greatest OAS 3.2 with ease.

Phil Sturgeon

Phil Sturgeon

— 4 min read

You might have heard the news that OpenAPI v3.2 has been released. If you missed that news you should join our newsletter, because we would have let you know.

OpenAPI 3.2... Finally!
The long-awaited launch of the newest version of the OpenAPI standard, plus JSON Streaming, Scaling API Workflows, a new RPC protocol, and a peek at Bluesky’s AT Protocol.
APIs You Won't HateAlexander Karan

Whenever a new version of anything is launched, whether that's a description language or a programming language, it can be bittersweet news. On the one hand, there's handy new features that will make your life a whole lot easier, but on the otherhand you have to "do stuff" now.

Many OpenAPI tooling creators are more familiar with that double-edged sword, and have set out to make the upgrade as easy as possible, with CLI tooling you can run against any OpenAPI document.

What are the differences

OpenAPI v3.2 is entirely additional, with no breaking changes. Mainly there are some extensions that are no longer needed.

  1. Tags x-displayName can be handled with the new summary keyword.
  2. Tags x-tagGroups can be handled with the new parent keyword.
Enhanced Tags
For API designers and writers wishing formalize their API in an OpenAPI Description document.
OpenAPI Documentation

Other than that... it's mostly changing openapi: 3.1 to openapi: 3.2 and looking to see if any of the new features are particularly useful.

Some of you might still be stuck on OpenAPI v3.0 or god forbid the old "Swagger" 2.0 (🤢). Either of these tools will help you make that jump in one go.

CLI: OpenAPI Format

OpenAPI Format is an amazingly useful CLI and web tool, and one that we used to help convert old timey API Blueprint to OpenAPI v3.1 in the migration guide from Apairy to Bump.sh.

Goodbye Apiary.io, You’ll Be Missed
Today we say farewell to a legend in the API documentation space as O.G. API design-first solution Apiary.io shuts its doors.
APIs You Won't HatePhil Sturgeon

The NodeJS CLI not only handles generally tidying up OpenAPI documents, but it can also upgrade OpenAPI document versions from v3.0 to v3.2.

npm install openapi-format

openapi-format openapi.json -o openapi-3.2.json --convertTo "3.2"

If you need to convert from Swagger 2.0 you can bung it through swagger2openapi first, or have a go with the following.

TypeScript: Scalar's OpenAPI Upgrader

Scalar are a new player aiming to take Stoplight's place now that it's pretty much binned off after the acquisition by SmartBear Scalar is not only creating a full OpenAPI editing, API reference documentation, mocking, SDK integration, full lifecycle package, but they're also doing it with the same sort of dedication to open-source tooling that Stoplight had back in the day.

Go and have a sift through the scalar/scalar GitHub monorepo if you're curious. There are countless packages that do all sorts of things, and the main work that needs doing is just documenting it all. I was rummaging about the other day and spotted scalar/openapi-upgrader, which does exactly what it says on the tin: upgrades OpenAPI documents all the way from 2.0 to 3.2.

This package is baked into the larger scalar/cli, but at time of writing v1.3.3 of the package does have any interface to allow the OAS 3.2 upgrade to happen. It's still experimental and this will only get you to OAS 3.1.

$ npm install @scalar/cli 

$ scalar document upgrade openapi.yaml --output openapi.31.yaml

Whilst it's not ready for CLI use, the TypeScript interface may well be interesting to those building tooling, web interfaces, or complicated workflows that need a bit more than a CLI to work with. 

import { upgrade } from '@scalar/openapi-upgrader'

const OPENAPI_DOCUMENT = {
  swagger: '2.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
}

// We need to explicitly pass '3.2' to upgrade to OpenAPI 3.2
const document = upgrade(OPENAPI_DOCUMENT, '3.2')

console.log(document.openapi)
// Output: 3.2.0

Give it a whirl and get back in the comments with feedback, or open some issues to help the Scalar team make this excellent.

Read more