What is OpenAPI? — REST API Specification Explained
Definition
OpenAPI (formerly known as Swagger) is a specification for describing RESTful APIs using a standard, language-agnostic format. An OpenAPI document (written in YAML or JSON) provides a machine-readable definition of every API endpoint, input parameter, response format, authentication method, and more.
The OpenAPI Specification (OAS) started life as Swagger in 2011, created by Tony Tam and the team at Reverb Technologies. In 2016, the specification was donated to the OpenAPI Initiative under the Linux Foundation and renamed OpenAPI. Swagger remained the name of the tooling ecosystem.
OpenAPI 3.0 vs 3.1
| Feature | OpenAPI 3.0 | OpenAPI 3.1 |
|---|---|---|
| JSON Schema | Draft 07 (custom subset) | Full JSON Schema 2020-12 |
| Format | YAML / JSON | YAML / JSON |
| Webhooks | ❌ | ✅ (native support) |
| Discriminator Mapping | ✅ | ✅ (improved) |
| Examples | Multiple examples | Multiple examples (improved) |
| Null Values | Limited | Full support via nullable / type: null |
| Path Parameters | Required by default | Can be declared optional |
| License Info | SPDX identifier | SPDX identifier (improved) |
| Release Year | 2017 | 2021 |
OpenAPI Document Structure
An OpenAPI spec is organized into top-level sections:
openapi: 3.1.0
info:
title: User Management API
version: 1.0.0
description: API for managing users and their posts
contact:
name: API Support
email: support@example.com
license:
name: MIT
identifier: MIT
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging.example.com/v1
description: Staging server
paths:
/users:
get:
summary: List all users
...
post:
summary: Create a new user
...
components:
schemas:
User:
...
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWTRoot-Level Fields
| Field | Required | Description |
|---|---|---|
openapi |
✅ | OpenAPI specification version |
info |
✅ | Metadata about the API |
servers |
❌ | Server connection URLs |
paths |
✅ | Available endpoints and operations |
components |
❌ | Reusable schemas, responses, parameters |
security |
❌ | Global security requirements |
tags |
❌ | Tag grouping for operations |
externalDocs |
❌ | External documentation links |
Paths and Operations
Each path defines one or more HTTP methods:
paths:
/users:
get:
tags: [Users]
summary: Retrieve all users
operationId: listUsers
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 20
- name: offset
in: query
required: false
schema:
type: integer
default: 0
responses:
"200":
description: A paginated list of users
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
"401":
$ref: "#/components/responses/Unauthorized"
post:
summary: Create a new user
operationId: createUser
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateUserRequest"
responses:
"201":
description: User created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/User"
/users/{userId}:
get:
summary: Get a user by ID
operationId: getUser
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: The requested user
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
description: User not foundSchemas (Data Models)
Schemas define the structure of request and response data using JSON Schema:
components:
schemas:
User:
type: object
required: [id, name, email]
properties:
id:
type: string
format: uuid
description: Unique identifier
name:
type: string
minLength: 1
maxLength: 100
email:
type: string
format: email
role:
type: string
enum: [admin, user, moderator]
default: user
createdAt:
type: string
format: date-time
avatar:
type: string
format: uri
nullable: true
example:
id: "550e8400-e29b-41d4-a716-446655440000"
name: "Alice Johnson"
email: "alice@example.com"
role: "admin"
createdAt: "2026-01-15T10:30:00Z"
avatar: null
CreateUserRequest:
type: object
required: [name, email]
properties:
name:
type: string
email:
type: string
format: email
role:
type: string
enum: [user, moderator]
default: userSecurity Schemes
OpenAPI supports multiple authentication methods:
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Enter your JWT token
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Enter your API key
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.example.com/authorize
tokenUrl: https://auth.example.com/token
scopes:
read: Read access
write: Write access
# Apply globally or per-operation
security:
- bearerAuth: []Code Generation
One of OpenAPI's most powerful features is code generation. Tools like OpenAPI Generator and Swagger Codegen can generate:
| Artifact | Examples |
|---|---|
| Server stubs | Node.js, Python, Go, Java, Ruby, PHP, Rust |
| Client SDKs | TypeScript, Python, Swift, Kotlin, Java |
| API documentation | Swagger UI, Redoc, Stoplight |
| API tests | Postman collections, REST Assured, pytest |
| Infrastructure | Terraform, Kubernetes manifests |
# Generate a TypeScript client
npx @openapitools/openapi-generator-cli generate \
-i spec.yaml \
-g typescript-fetch \
-o ./generated/client
# Generate a Python server
npx @openapitools/openapi-generator-cli generate \
-i spec.yaml \
-g python-flask \
-o ./generated/serverSwagger UI
Swagger UI renders OpenAPI specifications into interactive documentation:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css"
href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js">
</script>
<script>
SwaggerUIBundle({
url: "/openapi.yaml",
dom_id: "#swagger-ui",
});
</script>
</body>
</html>Swagger UI features include:
- Interactive endpoint testing — Try requests directly in the browser
- Schema exploration — View request/response models
- Authentication — Enter API keys and tokens
- Download — Export specification files
LangStop OpenAPI & API Tools
- OpenAPI Editor — Design and validate OpenAPI 3.x specifications
- OpenAPI Diff — Compare OpenAPI specifications side by side
- REST API Client — Send HTTP requests and test API endpoints
- JSON Schema GUI Builder — Visually build JSON schemas
- JSON Validator — Validate JSON syntax