Reference
OpenAPI Specification Guide
Complete reference for OpenAPI 3.0 schema structure, components, and best practices for documenting REST APIs.
What is OpenAPI?
OpenAPI Specification (formerly Swagger) is a standard, language-agnostic interface for RESTful APIs. It allows both humans and computers to understand API capabilities without accessing source code.
Benefits
- • Auto-generate documentation
- • Generate client SDKs
- • API testing & validation
- • Mock server generation
Supported Tools
- • Swagger UI / Redoc
- • Postman / Insomnia
- • AWS API Gateway
- • Mock API Builder
Document Structure
OpenAPI 3.0 Root Object
bash
| Field | Required | Description |
|---|---|---|
| openapi | Yes | OpenAPI version (3.0.0 or 3.0.1) |
| info | Yes | API metadata (title, version, description) |
| servers | No | Server connection info |
| paths | Yes | Available endpoints and operations |
| components | No | Reusable schemas, parameters, responses |
| security | No | Global security requirements |
| tags | No | Tags for grouping operations |
Info Object
API Metadata
plaintext
title: API name (required)
version: API version (required, use semver)
description: Supports Markdown formatting
Servers Object
Server Configuration
bash
Server Selection
Tools like Swagger UI allow users to select which server to use for testing. List servers in order of preference (production first).
Paths Object
API Endpoints
Complete Path Example
typescript
HTTP Method Fields
| Field | Type | Description |
|---|---|---|
| summary | string | Short description |
| description | string | Detailed description (Markdown) |
| operationId | string | Unique operation identifier |
| tags | array | Grouping tags |
| parameters | array | Query, path, header parameters |
| requestBody | object | Request body definition |
| responses | object | Possible responses (required) |
| security | array | Override global security |
Parameters
Parameter Locations
bash
Request Body
Request Body Definition
bash
Responses
Response Definitions
typescript
Components & Schemas
Reusable Components
typescript
Data Types & Formats
Schema Data Types
| Type | Format | Example |
|---|---|---|
| string | - | "Hello World" |
| string | "user@example.com" | |
| string | uri | "https://example.com" |
| string | date | "2024-01-15" |
| string | date-time | "2024-01-15T10:30:00Z" |
| string | password | ****** |
| string | byte | Base64 encoded |
| string | binary | File upload |
| integer | int32 | 123 |
| integer | int64 | 9223372036854775807 |
| number | float | 123.45 |
| number | double | 123.456789 |
| boolean | - | true / false |
| array | - | [1, 2, 3] |
| object | - | { } |
Validation Keywords
bash
Security Schemes
Authentication Methods
bash
Tags & Organization
Grouping Endpoints
bash
OpenAPI Best Practices
Use components: Define reusable schemas, parameters, and responses
Provide examples: Include request/response examples for every endpoint
Use operationId: Unique IDs help with code generation and tooling
Document errors: Define all possible error responses with schemas
Use tags wisely: Group related endpoints for better organization
Add descriptions: Write clear descriptions for all objects and fields
Validate schemas: Use validation keywords (min/max, pattern, enum)
Version your API: Include version in server URL (/v1, /v2)
Mark deprecations: Use deprecated: true for phased-out endpoints
Use proper formats: date-time, email, uri for better validation
Keep it in sync: Auto-generate from code or update with every change
Validate your spec: Use tools like Swagger Editor to catch errors