OpenAPI / Swagger
The standard, machine-readable contract that describes exactly what an API does — and lets tools generate docs, clients and tests from it automatically.
What it is
About OpenAPI / Swagger
OpenAPI (formerly the Swagger Specification) is a language-agnostic, YAML and JSON-based standard for describing a REST API's endpoints, request and response schemas, authentication and error responses in a single machine-readable document. Tools built around the spec (Swagger UI, Swagger Editor, Redoc) auto-generate interactive documentation, client SDKs and server stubs directly from that document, keeping documentation in sync with the actual API contract. It's the de facto standard for API-first design across the software industry.
What you can do with it
Capabilities
Define an API's endpoints, parameters, request and response schemas and auth in one spec file
Auto-generate interactive API documentation from the spec (Swagger UI and Redoc)
Generate client SDKs and server stubs in multiple languages from the same spec
Validate API implementations against the documented contract (contract testing)
Design APIs collaboratively before writing implementation code ('API-first' workflow)
How to learn it
Learning Resources
The official OpenAPI Specification documentation (openapis.org)
Swagger's own free 'Swagger Editor' playground for hands-on practice
SmartBear's free OpenAPI and Swagger tutorials and webinars
Practise by writing an OpenAPI spec for an existing API you use, then generating docs from it
Pro Tip
Design the OpenAPI spec before writing the endpoint code, not after — 'spec-first' catches inconsistent naming and missing error cases early, while writing the spec retroactively usually just documents whatever the code happened to do.
Skills that use this tool
Roles that use this tool