Glossary · web
OpenAPI
Definition
OpenAPI Specification (formerly Swagger) is an open standard for describing REST APIs in machine-readable format. Written in YAML or JSON, it documents endpoints, parameters, response schemas, and auth methods. Swagger UI auto-generates interactive documentation.
Detailed explanation
OpenAPI emerged from the Swagger Specification in 2016 and is maintained by the OpenAPI Initiative under the Linux Foundation. OpenAPI 3.1 is the current version. It serves as an API 'contract' — backend and frontend teams develop independently against the same spec.
Tools: Swagger UI (interactive docs), Swagger Editor (spec writing), Stoplight, Redoc, Postman (auto-import), openapi-generator (client SDK generation). In Next.js: swagger-jsdoc + swagger-ui-react are common.
Why it matters: API-first development lets frontend set up a mock server from the spec without waiting for backend. Ready guide for 3rd-party integration developers. API versioning (v1, v2) managed in the spec. In Turkey: 'no API docs' is the biggest time-waster in integration projects.
Use cases
→REST API documentation
→API-first development contract
→3rd-party integration guide
→Automated client SDK generation
→API testing (Postman collection)
Pros
- +Machine-readable → automated tooling
- +Independent frontend + backend development
- +Interactive docs (Swagger UI)
- +Automatic SDK generation
Cons
- −Keeping spec and code in sync
- −Maintenance overhead for complex schemas
- −Different standard for GraphQL (GraphQL SDL)
- −Learning curve (YAML/JSON spec syntax)
Related terms
Related services
Planning a project around OpenAPI?
In a 30-minute discovery call we share a written architecture + cost + team recommendation tailored to your project.
Start a discovery call