Stop 33 of 42 · The Blueprints · Exposed API docs (OpenAPI)

The staff manual in the lobby

The bank’s staff manual lists every window, every form and every rule, including the ones for managers only. A copy was left on a table in the lobby. Mallory sits down and reads it from cover to cover.

Severity Medium–HighCategory API ExposureThe BlueprintsSources checked 25 Oct 2026

Watch it happen

Play it as

The full staff manual is in the public lobby. Mallory reads which windows exist and which skip the badge check, and goes straight to the weakest one.

Arrival

The bank’s staff manual describes every window: what to ask, which forms to fill, who needs a badge. Alice walks in for a refund, and Mallory follows her.

1 / 5

In bank terms and app terms

In the bank	In your app
Staff manual	OpenAPI / Swagger spec, served at /docs, /swagger, /openapi.json, /api-docs
Lists every window and form	Every endpoint, parameter and response shape
Manager-only operations in the manual	Internal and admin routes documented in the public spec
“Badge required” notes	Security schemes in the spec, which should match what the server enforces

Are you exposed?

You might be exposed if…

Visiting /docs, /swagger, /api-docs or /openapi.json on your live site shows the full API.
Your spec documents internal, admin or billing operations, or has endpoints marked with security: [].
The spec has no global security setting, so endpoints look open, or it lists plain http:// servers.

What to do about it

Serve the docs UI and spec only in development, or put them behind login in production. Publish a trimmed public edition if customers need docs.
Remove admin and internal operations from any public spec, and set a global security scheme.
Remember the spec is not the protection. Enforce authentication and authorization in the server for every route.

Track these in your to-do list →

What it looks like in code

# GOOD: Don't serve OpenAPI spec in production
# Only enable in development:
if (process.env.NODE_ENV === "development") {
  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec))
}

# GOOD: If you must serve it, add auth
app.use("/api-docs", authMiddleware, swaggerUi.serve, swaggerUi.setup(spec))

# GOOD: Remove internal endpoints from the public spec
# Keep a separate internal-api.yaml for internal documentation

Ask your AI tool to fix it

Paste this into Cursor, Claude, Lovable, Bolt or whatever you build with.

Prompt

Review how our OpenAPI/Swagger docs are served. Disable /docs, /swagger and /openapi.json in production or require authentication, remove internal and admin operations from any public spec, add a global security scheme, and use https server URLs. Confirm each documented endpoint enforces auth on the server. List the changes.

Where this comes from

The facts, figures and fixes on this page were checked against these sources on 25 Oct 2026. They are linked so you can check for yourself.

OpenAPI Specification (latest)OpenAPI InitiativeTop-level security applies to all operations; an empty security array removes it for an operation
Describing API SecurityOpenAPI InitiativeSecurity schemes are declared once and referenced globally or per operation
API Server and Base URLSwaggerThe servers list holds the API URLs; plain http:// URLs are valid, so use https:// explicitly
Metadata and Docs URLsFastAPIDocs at /docs and schema at /openapi.json by default; disable with docs_url=None or openapi_url=None
API9:2023 Improper Inventory ManagementOWASPKeep an API inventory; unneeded exposed hosts and outdated docs raise risk

Spot a mistake or something out of date? Report a correction · How these guides are made and checked

Go deeper in isitsecure

The free, open-source scanner checks for most of the problems in these guides.