OpenAPI
Also known as: OpenAPI Spec, Swagger
Quick definition
OpenAPI is a specification format for describing REST APIs in a machine-readable JSON or YAML document. The spec captures every endpoint, parameter, request body, response shape, and authentication scheme — and toolchains use it to auto-generate SDKs, interactive documentation, mocks, and API tests.
What is OpenAPI?
OpenAPI is a specification format for describing REST APIs in a machine-readable document — typically JSON or YAML. The spec captures the complete API contract: every endpoint, the HTTP verb it accepts, the parameters it takes, the request body schema, the response body schema, the authentication scheme, the error responses, and inline documentation. The OpenAPI document is the source of truth for the API; humans read it to understand the contract, machines read it to auto-generate clients and tooling.
OpenAPI started as Swagger in 2010, was donated to the Linux Foundation in 2015, and renamed to OpenAPI Specification (OAS). The current major version is 3.x. The original Swagger UI has since been complemented by alternatives like Stoplight, Redoc, and Scalar — all consume OpenAPI documents and render them as interactive browsable docs.
What you can do with an OpenAPI spec
Five practical uses. (1) Auto-generated client SDKs — tools like openapi-generator and Stainless produce TypeScript, Python, Go, and other clients directly from the spec; no hand-coding. (2) Interactive documentation — Swagger UI, Stoplight, Scalar render the spec as browsable docs with try-it-now request execution. (3) Mock servers — generate a mock backend that responds with example data, useful for frontend development before the real API is ready. (4) API tests — frameworks like Dredd test the actual API against the spec to catch contract drift. (5) AI agent integration — modern AI tools can read the OpenAPI spec to understand what the API does and generate appropriate calls.
CodivUpload publishes its OpenAPI spec publicly at api.codivupload.com/public-openapi.json. The published spec is the source of truth for our auto-generated TypeScript and Python SDKs (codivupload on npm and PyPI), the interactive docs at docs.codivupload.com, and AI agents using our MCP server.
Frequently asked questions
What's the difference between OpenAPI and Swagger?+
Same thing. Swagger was the original name of the project (created 2010); the spec was renamed OpenAPI in 2015 when donated to the Linux Foundation. The Swagger brand survives on tools (Swagger UI, Swagger Editor); the spec itself is OpenAPI.
Can I use OpenAPI for non-REST APIs?+
OpenAPI is REST-specific. For GraphQL, the equivalent is the GraphQL Schema (introspection). For gRPC, .proto files. Each style has its own spec format.
How do I publish my own OpenAPI spec?+
Two paths. (1) Hand-write the YAML/JSON in a structured editor like Stoplight or Swagger Editor. (2) Auto-generate from your API code — most modern API frameworks (FastAPI, Hono, NestJS, Django REST) emit OpenAPI from the route definitions. Auto-generation keeps the spec always-correct as the code evolves; hand-writing risks drift.
Browse our OpenAPI spec
Full machine-readable spec at api.codivupload.com/public-openapi.json. Interactive Scalar docs at docs.codivupload.com. Auto-generated SDKs in TypeScript and Python.
See API docsRelated glossary terms