openapi-format | Format, Sort and Filter 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

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

Features

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

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.

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.

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

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.