openapi-format

Filtering

Strip matching items from your OpenAPI document based on methods, tags, flags, and more.

Try filtering in the Playground

CLI Usage

Terminal
npx openapi-format openapi.json -o output.json --filterFile customFilter.yaml
customFilter.yaml
flags:
  - x-visibility
flagValues: []
tags: []
operationIds:
  - addPet
  - findPetsByStatus

Filter Options Reference

Type Description Example
methods Remove matching HTTP methods ['get','post']
inverseMethods Keep only these methods ['get','post']
tags Remove matching tags ['pet','user']
inverseTags Keep only these tags ['pet','user']
operationIds Remove matching operation IDs ['findPets','updatePet']
inverseOperationIds Keep only these operation IDs ['findPets']
operations Remove matching method::path combos ['GET::/pets','PUT::/pets']
flags Remove items with these custom flags ['x-exclude','x-internal']
inverseFlags Keep only items with these flags ['x-public']
flagValues Remove items matching flag + value ['x-version: 1.0']
inverseFlagValues Keep only matching flag + value ['x-version: 2.0']
responseContent Remove response content types ['application/xml']
inverseResponseContent Keep only these response types ['application/json']
requestContent Remove request body content types ['application/xml']
inverseRequestContent Keep only these request types ['application/json']
unusedComponents Remove unreferenced components ['schemas','examples']
stripFlags Strip flag properties (keep parent) ['x-internal']
preserveEmptyObjects Keep empty objects true or ['schema']
textReplace Search & replace text values [{searchFor, replaceWith}]

Filter by Methods

Remove all operations matching specified HTTP methods. Use inverseMethods to keep only specified methods.

filter.yaml
methods:
  - get
  - put
Before
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: Finds Pets by status
    put:
      summary: Update an existing pet
    post:
      summary: Add a new pet
After — GET and PUT removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    post:
      summary: Add a new pet

Filter by Tags

Remove all operations tagged with specified values:

filter.yaml
tags:
  - pet
Before
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      tags:
        - pet
      summary: List all pets
    post:
      tags:
        - pet
      summary: Add a new pet
  /users:
    get:
      tags:
        - user
      summary: List all users
After — 'pet' operations removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - user
      summary: List all users

Filter by operationIds

Remove specific operations by their operationId:

filter.yaml
operationIds:
  - findPetsByStatus
Before
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      operationId: findPetsByStatus
      summary: Finds Pets by status
    post:
      operationId: addPet
      summary: Add a new pet
After — findPetsByStatus removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    post:
      operationId: addPet
      summary: Add a new pet

Filter by Operations

Target specific method + path combinations using the METHOD::path format. Supports wildcards:

filter.yaml
operations:
  # Exact match
  - "GET::/pets"
  # All methods on a path
  - "*::/pets"
  # All sub-paths
  - "GET::/pets/*"
  # Full wildcard
  - "*::/pets/*"
Before (operations: ['PUT::/pets'])
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: Finds Pets by status
    put:
      summary: Update an existing pet
  /users:
    get:
      summary: List all users
After — PUT /pets removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: Finds Pets by status
  /users:
    get:
      summary: List all users

Filter by Flags

Remove items that have a specific custom property (e.g. x-internal):

filter.yaml
flags:
  - x-internal
Before
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
  /internal/metrics:
    get:
      x-internal: true
      summary: Get metrics
  /internal/health:
    get:
      x-internal: true
      summary: Health check
After — internal endpoints removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets

Filter by Flag Values

Match flag + value combinations, including array values:

filter.yaml
flagValues:
  - x-version: 1.0
  - x-version: 3.0
Before
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      x-version: 1.0
      summary: List pets (v1)
    post:
      x-version: 2.0
      summary: Add pet (v2)
  /users:
    get:
      x-version: 3.0
      summary: List users (v3)
After — v1.0 and v3.0 removed
openapi: 3.0.0
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    post:
      x-version: 2.0
      summary: Add pet (v2)

Filter Response Content

Remove specific content types from responses:

filter.yaml
responseContent:
  - application/xml
Before
paths:
  /pet:
    post:
      summary: Add a new pet
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
After — XML content removed
paths:
  /pet:
    post:
      summary: Add a new pet
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

Remove Unused Components

Strip unreferenced items from the components section. Recursively removes nested unused components (up to 10 levels).

filter.yaml
unusedComponents:
  - schemas
  - parameters
  - examples
Before
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
    Error:
      type: object
    Category:
      type: object
After — Error & Category removed (unused)
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object

Strip Flags

Remove only the flag properties while keeping the parent operation intact:

filter.yaml
stripFlags:
  - x-internal
  - x-beta
Before
paths:
  /pets:
    get:
      x-internal: true
      x-beta: true
      summary: Finds Pets
      operationId: findPets
After — flags removed, operation kept
paths:
  /pets:
    get:
      summary: Finds Pets
      operationId: findPets

Text Replace

Search and replace text across descriptions, summaries, and URLs:

filter.yaml
textReplace:
  - searchFor: 'Pets'
    replaceWith: 'Dogs'
  - searchFor: 'swagger.io'
    replaceWith: 'openapis.org'
Before
openapi: 3.0.0
info:
  title: Pets API
  description: Manage your Pets
paths:
  /pets:
    get:
      summary: Find Pets by status
      description: Returns Pets from swagger.io
After — text replaced
openapi: 3.0.0
info:
  title: Dogs API
  description: Manage your Dogs
paths:
  /pets:
    get:
      summary: Find Dogs by status
      description: Returns Dogs from openapis.org