Skip to main content

How to Extract Out a Few Swagger/OpenAPI APIs into another document

Extracting out a few APIs comes handy when you’re documenting something about a specific API on Confluence or if you have an API Gateway that has only exposed a few of the APIs from your application.

openapi-filter ( can be used to extract out these APIs from your swagger/openapi document.

Mark the APIs that you want to extract out with the following flag: x-internal: true. For example,

openapi: 3.0.0
  title: API
  version: 1.0.0
      x-internal: true

Run the following command (where source.yaml is your input file):

npx openapi-filter --inverse --valid --strip -- source.yaml target.yaml

The APIs marked with x-internal: true will be extracted out in target.yaml.


--inverse: to include the APIs marked (and not exclude them, which is the default filter/behavior).
--valid: to copy all the other associated objects (and not just the paths)
--strip: to remove the flags which were added manually


Works with OpenAPI/Swagger 2.0 and 3.0.x and AsyncAPI definitions.