Format, Sort & Filter your OpenAPI definitions

A CLI and library to sort, filter, and format OpenAPI specs — making them consistent, clean, and diff-friendly.

$ npx openapi-format openapi.yaml

Trusted by the OpenAPI community

150+ GitHub Stars

320K+ Monthly Downloads

87 Versions Released

More OpenAPI tools from the community can be found on openapi.tools .

Features

Sort

Alphabetically sort fields, paths, and components for consistent ordering.

Read docs

Filter

Remove internal endpoints, tags, or unused components before publishing.

Read docs

Format

Standardise casing, indentation, and structure across your specs.

Read docs

Overlay

Apply overlays to add or override parts of your OpenAPI document.

Read docs

Split & Bundle

Split large specs into files or bundle multiple files into one.

Read docs

Convert

Convert between JSON and YAML, or between OpenAPI versions.

Read docs

Use Cases

Public Docs

Strip internal endpoints and sort your spec before publishing external documentation.

Maintenance

Keep large OpenAPI files readable and diff-friendly for easier code reviews.

CI/CD

Automate formatting and filtering in your pipeline to enforce spec standards.

Before & After

Before

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets/{petId}:
    get:
      summary: Get pet by ID
  /pets:
    post:
      summary: Create a pet
    get:
      summary: List all pets
components:
  schemas:
    Pet:
      type: object
    Error:
      type: object

After

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  '/pets':
    get:
      summary: List all pets
    post:
      summary: Create a pet
  '/pets/{petId}':
    get:
      summary: Get pet by ID
components:
  schemas:
    Error:
      type: object
    Pet:
      type: object

Quick Start

Start with the basics: format, sort, filter, and convert your OpenAPI files with a single CLI.

Format a spec

npx openapi-format openapi.yaml -o formatted.yaml

Sort & filter

npx openapi-format openapi.yaml --sortFile sort.json --filterFile filter.json

Convert to JSON

npx openapi-format openapi.yaml -o openapi.json

Install

npm install --save openapi-format

Explore more options

Online Playground

Explore openapi-format in the browser

The online playground lets you format, filter, sort, compare, and preview OpenAPI documents without installing anything locally.

Test config ideas, validate overlays, preview changes to your OpenAPI spec, and share the final result.

The OpenAPI Format Playground showing code input and formatted code output side by side.

Code in, formatted spec out

1/6

Compare your original document with the formatted output side by side while sort, filter, and overlay settings update the result immediately.

The OpenAPI Format Playground showing a rendered API preview next to the source document.

Preview the rendered API docs

1/6

Switch the output pane from raw code to a docs preview to inspect operations, parameters, and responses without leaving the playground.

The OpenAPI Format Playground showing the visual editor for an OpenAPI operation.

Edit with a visual UI

1/6

Move between code, UI editing, and preview modes depending on whether you want to inspect structure, tweak operations, or validate the result.

The OpenAPI Format Playground showing the filter options dialog with operation IDs selected.

Filter the spec before publishing

1/6

Use the filter dialog to narrow the document by operation IDs, methods, tags, and other dimensions before exporting a cleaner public version.

The OpenAPI Format Playground showing overlay actions configured for an OpenAPI document.

Manage overlay actions visually

1/6

Build and inspect overlay actions in a structured UI so targeted updates are easier to review than hand-editing larger documents.

The OpenAPI Format Playground showing a diff view between the original and updated OpenAPI document.

Review every change in diff view

1/6

Open a focused before-and-after diff to verify exactly what changed before you copy the output back into your project.

Explore the Docs

Everything you need to get started — from installation to advanced programmatic usage.

Claude, Codex & Skills

Use openapi-format with LLMs

Bring `openapi-format` into Claude, OpenAI Codex, and other agent-based workflows through Skills so OpenAPI tasks stay grounded in a consistent CLI-based workflow.

Install the skill once

Add the `openapi-format` skill to your local skills setup so LLM-assisted OpenAPI work stays predictable across editing, cleanup, and review tasks.

Install Command

npx skills add https://github.com/thim81/openapi-format --skill openapi-format

Prompt Example

Use openapi-format on ./openapi.yaml to sort paths by tags, remove internal endpoints, and write the result to ./openapi-public.yaml. Show me the exact command and the filter config you used.

Consistent outputs

Claude, Codex, and similar agents can rely on the same openapi-format behavior instead of inventing formatting rules on the fly.

Faster OpenAPI editing

Use agents to sort, filter, inspect, and refine OpenAPI files while keeping the actual spec transformations grounded in a real tool.

Tool-backed changes

Keep agent output in a real CLI workflow so OpenAPI changes are easier to inspect, reproduce, and trust.