Sorting

Sort OpenAPI fields in a defined order. Fields not specified keep their original order.

CLI Usage

Terminal

# Sort with defaults
npx openapi-format openapi.json -o openapi-sorted.json

# Sort with custom ordering
npx openapi-format openapi.json -o openapi-sorted.json --sortFile customSort.json

# Skip sorting entirely
npx openapi-format openapi.json -o output.json --no-sort

Default Sort Fields

The default sort order is stored in defaultSort.json. You can override it by providing a custom sort file.

Key	Ordered by
root	openapi → info → servers → paths → components → tags → x-tagGroups → externalDocs
get / post / put / patch / delete	operationId → summary → description → parameters → requestBody → responses
parameters	name → in → description → required → schema
requestBody	description → headers → content → links
responses	description → headers → content → links
content	By alphabet
components	parameters → schemas
schema / schemas	description → type → items → properties → format → example → default
properties	description → type → items → format → example → default → enum

Custom Sort File

Create a JSON or YAML file specifying your preferred field order per key:

customSort.json

{
  "root": ["openapi", "info", "servers", "paths", "components"],
  "get": ["summary", "description", "operationId", "parameters", "responses"],
  "schema": ["type", "description", "properties", "required"]
}

Sort Paths

Control the order of paths in your OpenAPI document using sortPathsBy:

Option	Description
original	Keep the original order (default)
path	Order alphabetically by path
tags	Order by the first tag of the first method

Terminal

npx openapi-format openapi.yaml -o openapi.sorted.yaml --configFile sort-paths.json

Put sortPathsBy inside sortSet to sort paths alphabetically:

Open Example in Playground

sort-paths.json

{
  "sort": true,
  "sortSet": {
    "sortPathsBy": "path"
  }
}

Example

Before

openapi: 3.0.0
info:
  title: Pets API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
  /auth:
    post:
      summary: Login
  /pets:
    get:
      summary: List pets

After (sortPathsBy: path)

openapi: 3.0.0
info:
  title: Pets API
  version: 1.0.0
paths:
  /auth:
    post:
      summary: Login
  /pets:
    get:
      summary: List pets
  /users:
    get:
      summary: List users

Sort Components

Sort items within the components section alphabetically:

Terminal

npx openapi-format openapi.json -o output.json --sortComponentsFile sortComponents.json

sortComponents.json

["schemas", "parameters", "headers", "requestBodies", "responses", "securitySchemes"]

Example

Before

components:
  schemas:
    Order:
      type: object
    Customer:
      type: object
    Address:
      type: object

After

components:
  schemas:
    Address:
      type: object
    Customer:
      type: object
    Order:
      type: object

Sort Component Properties

Sort properties within schema components alphabetically:

Terminal

npx openapi-format openapi.json -o output.json --sortComponentsProps

Example

Before

schemas:
  UserDto:
    type: object
    properties:
      lastName:
        type: string
      firstName:
        type: string

After

schemas:
  UserDto:
    type: object
    properties:
      firstName:
        type: string
      lastName:
        type: string