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	email	"user@example.com"
string	uri	"https://example.com"
string	date	"2025-01-15"
string	date-time	"2025-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

Previous: Postman Export Next: Authentication & Authorization

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

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

Data Types & Formats

Schema Data Types

Type	Format	Example
string	-	"Hello World"
string	email	"user@example.com"
string	uri	"https://example.com"
string	date	"2025-01-15"
string	date-time	"2025-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