OpenAPI Specification
A standard, language-agnostic format for describing REST APIs, enabling documentation, code generation, and testing.
In-Depth Explanation
OpenAPI Specification (formerly Swagger) is a standard format for describing REST APIs. It enables automatic documentation generation, client SDK generation, testing, and API development tooling.
OpenAPI components:
- Info: API metadata (title, version)
- Servers: API base URLs
- Paths: Endpoints and operations
- Components: Reusable schemas, parameters
- Security: Authentication definitions
Key benefits:
- Human and machine readable (YAML/JSON)
- Auto-generate documentation (Swagger UI)
- Generate client SDKs in many languages
- Enable API testing tools
- Contract-first development
Version history:
- Swagger 2.0 (now OpenAPI 2.0)
- OpenAPI 3.0 (major improvements)
- OpenAPI 3.1 (JSON Schema alignment)
Common tools:
- Swagger UI (interactive docs)
- Swagger Editor (spec editing)
- OpenAPI Generator (code generation)
- Postman (imports OpenAPI)
Business Context
OpenAPI standardises API documentation, making APIs more accessible to developers and enabling powerful tooling.
How Clever Ops Uses This
We document all APIs using OpenAPI for Australian businesses, ensuring clear specifications and enabling automated client generation.
Example Use Case
"Publishing an OpenAPI spec that automatically generates Swagger UI documentation, TypeScript client SDK, and Postman collection for API testing."