OpenAPI Specification (OAS)
The OpenAPI Specification (OAS) is a standard format for describing an HTTP API in a YAML or JSON file. The file lists every path and method, the parameters each one takes, request and response bodies as JSON Schema, status codes and authentication. Because tools can read it, one file can drive documentation, client libraries, server stubs, mock servers and contract tests. It started as the Swagger specification and was donated to the OpenAPI Initiative under the Linux Foundation in 2015.
How it works
A document starts with an openapi version and an info block, then a paths map from URL templates to operations. Shared shapes live under components/schemas and are referenced with $ref, so a Student schema is defined once and reused by every endpoint that returns one. Teams either write the file first and generate code from it (design-first) or generate the file from annotated code (code-first).
For the bootcamp student API, the path /api/v1/students/{id} has a get operation with one required path parameter, id, and two responses: "200", whose body is the Student schema, and "404" for an ID that does not exist. From that file, Swagger UI or Redoc renders browsable docs, and a generator such as openapi-generator or oapi-codegen produces a typed client and server handlers, so GET /api/v1/students/42 returns either a Student or a typed not-found error.
Why it matters in production
The spec is the contract between the team that runs an API and the teams that call it. If it is generated from code or checked in CI, docs and clients cannot drift from what the server does; a hand-written file that nobody checks goes stale fast. A linter and a breaking-change diff on every pull request catch a removed field or a renamed parameter before a client finds it in production. Many API gateways can import the same file to configure routes and validate requests.
See also
On the One2N blog
References
