How can I use OpenAPI overlays to remove internal endpoints before publishing documentation?

How can I use OpenAPI overlays to remove internal endpoints before publishing documentation? #

Most real-world APIs expose a mix of public-facing operations and internal-only endpoints used for administration, debugging, or internal tooling. When it’s time to publish documentation for external developers or partners, those internal endpoints should not appear. Rather than maintaining a second, manually pruned copy of your OpenAPI document, the OpenAPI Overlay Specification lets you declaratively remove those paths as a separate, reusable transformation step.

Why This Matters #

Manually deleting paths from a copy of your spec creates drift: every time the canonical document changes, someone has to remember to re-apply the same manual edits to the “public” copy. This is error-prone and doesn’t scale. An overlay expresses the removal as data, so it can be re-applied automatically every time the base document is regenerated.

Identifying Internal Endpoints #

A common convention is to tag internal operations, either with the tags array or with a vendor extension such as x-internal: true:

paths:
  /internal/admin/reindex:
    post:
      tags: [internal]
      x-internal: true
      summary: Trigger a manual search reindex
  /users:
    get:
      tags: [public]
      summary: List users

Having a consistent marker makes it much easier to target these operations from an overlay.

Writing the Overlay #

Using JSONPath, you can target specific paths directly by key, or use wildcard expressions matched against tags if your tooling supports conditional selection. The simplest and most reliable approach is to target exact path keys:

overlay: 1.0.0
info:
  title: Public Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/reindex']
    remove: true
  - target: $.paths['/internal/metrics']
    remove: true
  - target: $.paths['/internal/feature-flags']
    remove: true

Each remove: true action deletes the entire path item, including all HTTP methods defined under it.

Removing Individual Operations Instead of Whole Paths #

Sometimes only one method under a path is internal, while others are public. Target the specific operation instead of the whole path item:

actions:
  - target: $.paths['/orders'].delete
    remove: true

This keeps GET /orders and POST /orders visible while hiding the internal DELETE /orders operation.

Cleaning Up Orphaned Components #

Removing paths can leave orphaned schemas in components.schemas that are no longer referenced anywhere in the document. Overlays do not automatically prune unused components — this is typically handled by a follow-up linting or bundling step. Tools such as Redocly CLI can flag unused components after the overlay has been applied, so it’s good practice to run a bundle-and-lint step immediately after applying the overlay.

Applying the Overlay #

With Redocly CLI, applying an overlay is a single command:

redocly join openapi.yaml --overlay public-overlay.yaml -o public-openapi.yaml

The output is a new document with all internal endpoints removed, ready to be published to a documentation portal, without ever modifying the source file.

Automating This in Your Pipeline #

Because the overlay is just a file, it belongs in version control right alongside your OpenAPI document. A typical CI/CD job might:

Validate the base OpenAPI document.
Apply the “public” overlay to produce a redacted copy.
Publish the redacted copy to the external documentation portal.
Publish the untouched base document to an internal-only portal.

This keeps a single source of truth while producing two tailored outputs automatically on every merge.

For more background on how overlays work in general, see What is the OpenAPI Overlay Specification?. If you need to redact specific fields rather than whole endpoints, see How can I use OpenAPI overlays to redact sensitive fields from an OpenAPI document?.

Last updated on July 16, 2026.