> ## Content Index
> Fetch the complete content index at: https://apisyouwonthate.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Automatically Upgrade to OpenAPI v3.2
- URL: https://apisyouwonthate.com/blog/automaticly-upgrade-to-openapi-v3-2/
- Published: 2025-10-13T12:38:41.000Z
- Updated: 2025-10-16T12:41:30.000Z
- Description: Upgrade old OpenAPI/Swagger documents to the latest and greatest OAS 3.2 with ease.
- Author: Phil Sturgeon

You might have heard the news that [OpenAPI v3.2](https://spec.openapis.org/oas/v3.2.0?ref=apisyouwonthate.com) 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.![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/icon/apis-logo-square-17.png)APIs You Won't HateAlexander Karan![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/thumbnail/openapi-3.2.0-launch.jpg)](https://apisyouwonthate.com/newsletter/openapi-3-2-finally/)

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 TagsFor API designers and writers wishing formalize their API in an OpenAPI Description document.![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/icon/favicon-16.ico)OpenAPI Documentation![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/thumbnail/OpenAPI_Logo_Pantone-1-1.png)](https://learn.openapis.org/specification/tags.html?ref=apisyouwonthate.com)

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](https://www.npmjs.com/package/openapi-format?ref=apisyouwonthate.com) 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](https://apisyouwonthate.com/blog/goodbye-apiary-io/).

[Goodbye Apiary.io, You’ll Be MissedToday we say farewell to a legend in the API documentation space as O.G. API design-first solution Apiary.io shuts its doors.![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/icon/apis-logo-square-20.png)APIs You Won't HatePhil Sturgeon![](https://storage.ghost.io/c/b4/3e/b43eb8f8-cafd-49ee-ab1f-e4fe989d2890/content/images/thumbnail/farewell-apiary--1-.webp)](https://apisyouwonthate.com/blog/goodbye-apiary-io/)

The NodeJS CLI not only handles generally tidying up OpenAPI documents, but it can also [upgrade OpenAPI document versions](https://www.npmjs.com/package/openapi-format?ref=apisyouwonthate.com#cli-convertto-usage) 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](https://www.npmjs.com/package/swagger2openapi?ref=apisyouwonthate.com) 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](https://github.com/scalar/scalar/tree/main/packages?ref=apisyouwonthate.com) 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](https://www.npmjs.com/package/@scalar/openapi-upgrader?ref=apisyouwonthate.com), 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](https://www.npmjs.com/package/@scalar/cli?ref=apisyouwonthate.com), 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](https://www.npmjs.com/package/@scalar/openapi-upgrader?ref=apisyouwonthate.com) and get back in the comments with feedback, or open some issues to help the Scalar team make this excellent.