Features
- Language-agnostic API description format (YAML/JSON)
- Swagger UI for interactive API documentation
- Client and server code generation
- Request/response validation from spec
Pros
- Industry standard for API documentation
- Enables code generation across languages
- Interactive documentation for API consumers
Cons
- Spec files can become large and hard to maintain
- Keeping spec in sync with code requires discipline
- YAML syntax can be error-prone
Overview
OpenAPI (formerly Swagger) is the industry-standard specification for describing RESTful APIs. An OpenAPI document defines your API’s endpoints, request/response schemas, authentication methods, and more in a machine-readable YAML or JSON format.
From an OpenAPI spec, tools can generate interactive documentation (Swagger UI), client SDKs in dozens of languages, server stubs, and validation middleware. This “spec-first” approach ensures consistency between documentation and implementation, making APIs easier to consume and maintain.
When to Use
Use OpenAPI when building public REST APIs that need documentation, when generating client SDKs for API consumers, or when you want contract-first API development. It’s essential for any REST API consumed by external developers.
Getting Started
# openapi.yaml
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/users:
get:
summary: List users
responses:
"200":
description: Success
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"