Is OpenAPI the same as Swagger?

Swagger was the original name of the specification and is now the name of a tooling family built around it. The format itself has been called OpenAPI since version 3.

Does publishing an OpenAPI document create a security risk?

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

Should the specification be generated or written?

Generated documents stay accurate and describe the implementation. Written ones describe the intended contract and drift. Most teams generate and review, which gets most of both.

Glossary

OpenAPI

OpenAPI is a specification for describing an HTTP API in a machine-readable document: its paths, the parameters each one accepts, the shapes it returns, and the authentication it requires. Tooling reads that document to generate client libraries, render interactive documentation and drive tests. A published OpenAPI document is therefore both documentation for people and an interface contract for programs — which is why the gap between what it says and what the service does is more expensive than an out-of-date written page.

What the document contains

Paths and operations: every endpoint, and the HTTP methods each one answers.

Parameters and request bodies, with their types, so a client can be generated rather than written by hand.

Responses, keyed by status code, each with the shape of what comes back — including the error shapes, which written documentation routinely omits.

Security schemes: which credential each operation requires, declared once and referenced by the operations that need it.

Reusable components, so a shape defined once is referenced everywhere it appears rather than copied.

Why it drifts, and what the drift costs

A specification is written or generated at one moment and the service keeps changing. Nothing fails when the two disagree, so nothing announces the gap.

A document describing an endpoint that no longer exists sends integrators to build against something that will not answer.

A document describing an internal endpoint publishes an index of the surface you did not mean to expose — the more damaging direction of the same drift.

A document declaring no security scheme describes the API as fully public. Where that is untrue, every integrator starts from a false premise.

Generating the document from the code removes most of this, at the cost of a specification that describes the implementation rather than the intended contract.

Published, or not

Publishing the document is how integrators build against a public API, and it is the normal choice for one.

Serving an interactive documentation interface alongside it is a separate decision: it makes the API explorable from a browser, which is right for a public API and rarely right for an internal one.

Neither is required. Plenty of well-run APIs distribute the document privately to the integrators who need it.

What is not a defensible position is publishing one that has not been read recently, since its errors are now other people's code.

How it is observed

A published document is served at a conventional path or linked from the site, and is fetched and parsed rather than assumed.

The declared security schemes are read, which is what distinguishes an API documented as authenticated from one documented as open.

Cross-reading the document's paths against the endpoints really reachable is what turns it into a finding: a path in one and not the other is the drift worth acting on.

A declared scheme says what the document claims. Whether an endpoint enforces it is established by requesting it without credentials, not by reading the specification.

Frequently asked questions

Is OpenAPI the same as Swagger?: Swagger was the original name of the specification and is now the name of a tooling family built around it. The format itself has been called OpenAPI since version 3.
Does publishing an OpenAPI document create a security risk?: Not by itself — it is how integrators build against you. The risk is publishing one that describes endpoints you did not intend to expose, which is a content problem in the document.
Should the specification be generated or written?: Generated documents stay accurate and describe the implementation. Written ones describe the intended contract and drift. Most teams generate and review, which gets most of both.

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