Swagger OpenAPI Cheat Sheet

Updated 2026-04-29

Next Topic: Testing Library for Web Components Cheat Sheet

OpenAPI (formerly Swagger) is a language-agnostic, machine-readable specification standard for describing RESTful HTTP APIs. The specification allows both humans and computers to understand API capabilities without accessing source code or documentation through network inspection. OpenAPI descriptions can be written in YAML or JSON format, with YAML preferred for manual authoring due to readability and comment support. OpenAPI 3.1 achieved full JSON Schema Draft 2020-12 compatibility; OpenAPI 3.2 (released September 2025) added first-class streaming support, the QUERY HTTP method, hierarchical tags, and the $self document identity field. The OpenAPI Initiative also maintains two companion standards — the Overlay Specification (non-destructive spec patches) and the Arazzo Specification (API workflow sequences) — completing a three-spec ecosystem for API design, documentation, and orchestration.

What This Cheat Sheet Covers

This topic spans 26 focused tables and 249 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: OpenAPI Document StructureTable 2: Info Object FieldsTable 3: HTTP Methods (Operations)Table 4: Path and Operation FieldsTable 5: Parameter TypesTable 6: Parameter Definition FieldsTable 7: Data Types and FormatsTable 8: Schema Validation KeywordsTable 9: Schema CompositionTable 10: Request BodyTable 11: Content Types (Media Types)Table 12: Response Status CodesTable 13: Response Object FieldsTable 14: Security SchemesTable 15: Server Variables and URL TemplatingTable 16: Reusable Components ($ref)Table 17: Reference Resolution ($ref)Table 18: Specification Extensions (Vendor Extensions)Table 19: Common Design PatternsTable 20: API Documentation and ToolingTable 21: OpenAPI 3.1 vs 3.0 Key DifferencesTable 22: OpenAPI 3.2 vs 3.1 Key DifferencesTable 23: YAML vs JSON FormatTable 24: Best PracticesTable 25: OpenAPI Overlay SpecificationTable 26: Arazzo Workflow Specification

Table 1: OpenAPI Document Structure

Field	Example	Description
openapi	`openapi: 3.1.0`	• Required. Specifies the OpenAPI Specification version — `3.0.x`, `3.1.x`, or `3.2.x` are current • version determines available features and JSON Schema compatibility.
info	`info:` `title: My API` `version: 1.0.0`	• Required. Metadata about the API including title, description, version, contact, license, and terms of service • `title` and `version` are mandatory.
paths	`paths:` `/users:` `get: {...}`	Required (or `webhooks` or `components`). Defines available API endpoints and HTTP operations with their parameters, request bodies, and responses.
components	`components:` `schemas:` `User: {...}`	• Container for reusable objects — schemas, responses, parameters, examples, security schemes, and more • referenced via `$ref`.
servers	`servers:` `- url: https://api.example.com/v1`	• Array of server objects defining base URLs where the API is available • supports variable substitution for environment-specific URLs.

Table 1: OpenAPI Document Structure

Field	Example	Description
openapi	`openapi: 3.1.0`	• Required. Specifies the OpenAPI Specification version — `3.0.x`, `3.1.x`, or `3.2.x` are current • version determines available features and JSON Schema compatibility.
info	`info:` `title: My API` `version: 1.0.0`	• Required. Metadata about the API including title, description, version, contact, license, and terms of service • `title` and `version` are mandatory.
paths	`paths:` `/users:` `get: {...}`	Required (or `webhooks` or `components`). Defines available API endpoints and HTTP operations with their parameters, request bodies, and responses.
components	`components:` `schemas:` `User: {...}`	• Container for reusable objects — schemas, responses, parameters, examples, security schemes, and more • referenced via `$ref`.
servers	`servers:` `- url: https://api.example.com/v1`	• Array of server objects defining base URLs where the API is available • supports variable substitution for environment-specific URLs.

Swagger/OpenAPI Cheat Sheet

Table 1: OpenAPI Document Structure

Swagger/OpenAPI Cheat Sheet

Table 1: OpenAPI Document Structure