TopolearnOne accurate description replaces hand-written docs, SDKs and guesswork about an API.
The OpenAPI Specification (OAS) defines a standard way to describe an HTTP API in YAML or JSON: which paths exist, which operations (GET, POST...) they support, their parameters, request bodies, responses, and security requirements. The document is readable by humans and by tools.
What teams do with it:
- Documentation: Swagger UI, Redoc, Scalar and others render interactive reference docs with "try it" consoles.
- Code generation: typed client SDKs and server stubs in dozens of languages.
- Mocking: serve realistic fake responses before the backend exists.
- Validation and testing: check requests and responses against the contract, lint for consistency, detect breaking changes in CI.
- Gateways and AI agents import OpenAPI to configure routes or call APIs as tools.
Some history: OpenAPI began as Swagger 2.0 and was donated to the Linux Foundation's OpenAPI Initiative in 2015. "Swagger" now names SmartBear's tools. Version 3.0 (2017) restructured the format; 3.1 (2021) aligned schemas fully with JSON Schema 2020-12 and added webhooks; 3.2 (2025) is backwards compatible with 3.1 and adds features such as hierarchical tags, the QUERY method and streaming media types.
Two workflows exist: design-first (write the document, then implement) and code-first (generate the document from annotated code, as FastAPI or Spring do). Both work if the document stays the source of truth that is tested.
Example
# The smallest useful OpenAPI document
openapi: 3.1.1
info:
title: Todo API
version: 1.0.0
paths:
/todos:
get:
summary: List todos
responses:
'200':
description: The todos
content:
application/json:
schema:
type: array
items:
type: object
properties:
id: { type: integer }
title: { type: string }Remember
- OpenAPI describes HTTP APIs in YAML or JSON
- One document drives docs, SDKs, mocks and tests
- Swagger 2.0 became OpenAPI 3.x; Swagger now names tools
- Design-first or code-first, keep the document as the contract
Watch out for
- Treating the document as one-off documentation that drifts from the real API.