Home / Knowledge hub / OpenAPI specification
Knowledge hub
OpenAPI specification
A file that describes an API's endpoints so tools and people can read it.
What it means
The OpenAPI Specification is a standard format for describing an HTTP API in a file, written in YAML or JSON. It lists the endpoints, the verbs each accepts, the inputs and outputs, and how callers authenticate. Tools can read it to build documentation, client code and tests.
It is a description, not the API itself. The file can be accurate, out of date or incomplete, and the real service will behave however it was built, whatever the file claims. Anything that reads the file should therefore be checked against how the live service actually responds.
Why it matters
A current description is a map of your attack surface. It helps developers, testers and security tools find every endpoint. It also helps anyone who finds it, so a description published without thought can show routes, parameter names and internal hints to people who should not have them.
The larger danger is drift. If the file leaves out an endpoint that exists, nobody tests it, and it becomes a shadow API. If it says a route needs authentication but the code does not enforce it, the file gives false comfort.
How it shows up
You meet the specification as a file named openapi.yaml, as generated docs pages and as a Swagger-style interface left reachable in production. Check who can open those pages, whether internal-only routes appear in them, and whether the file is generated from the code or written by hand and forgotten.
Used well, it is a checking tool. Compare the file with real traffic to find undocumented routes. Use it to drive tests of each endpoint, and use its schemas to reject malformed requests, as covered in schema validation. Update it with every release, not once a year.
Questions people ask
OpenAPI specification, answered
Is OpenAPI the same as Swagger?
Closely related. Swagger was the original name of the specification and is now a family of tools. The specification itself is called OpenAPI and is maintained by the OpenAPI Initiative.
People often say Swagger when they mean an OpenAPI file or its docs page.
Should the OpenAPI file be public?
It depends on who the API is for. A public partner API benefits from public docs. An internal API usually should not show its full description to the internet.
Whatever you choose, make it a decision rather than a default.
Does having an OpenAPI file make an API secure?
No. It describes the API. It does not enforce anything unless you also use it to validate incoming requests against its schemas.
Treat it as documentation and a test input, not as a control on its own.
Can attackers use our OpenAPI file?
If it is reachable, yes. It lists routes and parameters in one place, which saves them the effort of exploring.
Hiding it is not a defence, though. The routes must be protected whether or not anyone has the map.
How do we keep it accurate?
Generate it from the code where you can, and fail the build when the two disagree. Compare it with production traffic now and then.
A file maintained only by hand will drift.
Related
Terms that sit next to this one
API inventory
A maintained list of every API you expose, who owns it and what it returns.
API schema validation
Rejecting requests that do not match the format the API says it accepts.
Shadow API
An API running in production that nobody has documented, tracked or secured.
REST API
A common web API style where URLs name things and HTTP verbs act on them.
Attack surface
Everything about your application an outsider can touch.
Does the map match the territory?
An API description tells us where to look, and traffic tells us what is really there. We test both, including routes the file forgot, and report only what we proved. Book a pilot on one app.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.