OpenAPI

OpenAPI (formerly Swagger) is a specification for describing HTTP APIs in a machine-readable format, typically YAML or JSON. An OpenAPI document defines an API's endpoints, request and response schemas, authentication, and examples, and is used to generate documentation, client SDKs, server stubs, and validation logic.

What it covers

• Paths and operations: URL templates with parameters, request and response definitions per method
• Schemas: data types using JSON Schema for request bodies, response bodies, and parameters
• Security: declares which schemes (Bearer, OAuth 2.0, API key) protect each operation
• Servers, tags, components: reusable definitions and metadata

Common tools

• Docs: Swagger UI, Redoc, Stoplight Elements, Scalar
• SDK generation: openapi-generator, OpenAPI Codegen, Speakeasy, Fern
• Editors: Stoplight Studio, Swagger Editor, Postman
• Runtime validation: Spectral, Prism, express-openapi-validator