What is OpenAPI? — REST API Specification Explained

OpenAPI is a specification for describing REST APIs using a standard format (JSON or YAML). It documents endpoints, request parameters, response schemas, authentication, and more, enabling automatic code generation, documentation, and testing.

What Is It?

OpenAPI (formerly Swagger) started as a specification by SmartBear in 2011 and became the OpenAPI Specification under the Linux Foundation in 2016. An OpenAPI document describes every aspect of an API: available endpoints, HTTP methods, parameters, request bodies, response schemas, authentication methods, and error codes.

How It Works

You write an openapi.yaml (or JSON) file that defines your API. Tools like Swagger UI generate interactive documentation from the file. Code generators (openapi-generator) create client SDKs and server stubs in 40+ languages. Validators check that your API implementation matches the specification.

Key Characteristics

• Industry standard — adopted by Google, Microsoft, AWS, and thousands of APIs
• Language agnostic — describes APIs in YAML/JSON, generates code for any language
• Interactive docs — Swagger UI lets users test endpoints from the browser
• Code generation — generates client SDKs and server stubs automatically
• Mock servers — generate realistic mock API responses from the spec

Common Use Cases

• Documenting REST APIs for internal teams and external developers
• Generating client SDKs for mobile and web applications
• API testing and validation against the specification
• Contract-first API development — write spec before implementation
• API marketplace integration — public APIs publish OpenAPI specs

Frequently Asked Questions