OpenAPI

Definition

OpenAPI is a language-agnostic specification for describing REST APIs in a machine-readable format, covering endpoints, request/response schemas, authentication, and metadata.

Overview

The OpenAPI Specification (formerly known as Swagger) defines a standard, YAML- or JSON-based way to describe a REST API's surface: its routes, HTTP methods, parameters, request bodies, response schemas, and security requirements. Because the description is machine-readable, tooling can automatically generate interactive documentation, client SDKs in multiple languages, server stubs, and validation logic straight from a single source of truth. Teams commonly write an OpenAPI document by hand or generate it from code annotations in frameworks such as FastAPI or Express.js, then feed it into tools like Swagger UI or Postman for exploration and testing. This contract-first or code-first workflow helps frontend and backend teams agree on an API's shape before or during implementation, reducing integration bugs and keeping documentation from drifting out of sync with the actual API. OpenAPI has become the de facto standard for describing REST APIs across the industry, and understanding it is a core skill covered in courses like API Design & Best Practices. It complements — rather than competes directly with — schema-first alternatives like GraphQL, which uses its own type system instead of the OpenAPI document format.

Key Concepts

• Machine-readable YAML or JSON description of an entire REST API
• Automatic generation of interactive documentation (e.g. Swagger UI)
• Client SDK and server stub generation in many programming languages
• Built-in support for describing authentication and security schemes
• Schema validation for requests and responses
• Widely supported by API gateways, testing tools, and IDEs
• Versioned specification (OpenAPI 3.x is the current major version)

Use Cases

Frequently Asked Questions

Related in Web