Is publishing an OpenAPI document a security risk?

Not by itself — it is how integrators build against you. The risk is publishing one that describes endpoints you did not mean to expose, which is a content problem in the document rather than a reason not to have one.

Should the interactive documentation interface be public too?

That is a separate choice from publishing the document. The interface makes the API trivially explorable from a browser, which is exactly what you want for a public API and rarely what you want for an internal one.

What does an empty security section actually mean?

That the document describes every operation as requiring no credential. If your API does require one, the specification is wrong and every integrator reading it starts from a false premise.

Tools

OpenAPI document checker

An OpenAPI document checker looks for a specification or a documentation interface served publicly, reads the security schemes it declares, and reports whether an explicit version appears in the API paths. A published specification is an asset for integrators and a map for everyone else, so the question it raises is not whether to publish one but whether the one being served still matches the service and still describes only the endpoints meant to be public.

What it establishes

Whether a machine-readable specification is served publicly, at one of the conventional locations or linked from the site.

Whether an interactive documentation interface is served alongside it, which is a separate decision from publishing the document itself.

Which security schemes the specification declares, and whether the operations reference them or leave themselves described as open.

Whether the paths carry an explicit version, which is what lets the API change without breaking the integrations already built on it.

The drift this is really about

A specification is written once and generated or edited afterwards, and the service keeps moving. The gap between the two grows silently because nothing fails when they disagree.

The expensive direction of that drift is a spec that still documents an endpoint removed from the service, which sends integrators to build against something that no longer answers.

The dangerous direction is a spec that documents an internal endpoint, because the document is then a published index of the surface you did not intend to publish.

A specification declaring no security scheme at all describes the API as fully public. Where that is untrue it misleads every integrator who reads it before writing a line.

What a clean result looks like

A specification whose paths match the endpoints the discovery check found, with nothing in it you do not recognise.

Security schemes declared, and referenced by the operations that require them, so a reader knows which calls need a credential before making one.

An explicit version in the paths or the hostname, so a breaking change can be shipped beside the current version rather than on top of it.

Documentation served from the same origin as the API, which avoids the separate CORS problem of a documentation interface calling across origins.

The limits, stated plainly

Only a publicly served document is read. A specification behind authentication, or distributed to integrators privately, is invisible to this and that is the intended behaviour.

The document is read as published; it is not validated against every rule of the OpenAPI schema.

A declared security scheme is a declaration. Whether the endpoint enforces it is established by the discovery check requesting it anonymously, not by reading the document.

No specification is not a finding. Plenty of good APIs publish none, and the check reports absence as absence.

What VeriFixScan uses

`api.documentation.public` detects a served specification or documentation interface. `api.documentation.auth_schemes` reads the security schemes declared in it.

`api.versioning` detects an explicit version in the observed API URLs or hostname.

Cross-reading these against `api.surface.detected` is what turns the document into a finding: an endpoint in one and not the other is the drift worth acting on.

When to run it

Before announcing an API to integrators, since the document is what they will build against and it is cheaper to correct before anyone has.

After a release that removed or renamed endpoints, which is when a hand-maintained specification starts describing a service that no longer exists.

After moving from a hand-written specification to a generated one, or the reverse, because the two rarely produce the same set of paths on the first attempt.

Frequently asked questions

Is publishing an OpenAPI document a security risk?: Not by itself — it is how integrators build against you. The risk is publishing one that describes endpoints you did not mean to expose, which is a content problem in the document rather than a reason not to have one.
Should the interactive documentation interface be public too?: That is a separate choice from publishing the document. The interface makes the API trivially explorable from a browser, which is exactly what you want for a public API and rarely what you want for an internal one.
What does an empty security section actually mean?: That the document describes every operation as requiring no credential. If your API does require one, the specification is wrong and every integrator reading it starts from a false premise.

Sources

VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.

Scan a website