Swagger OpenAPI Cheat Sheet

Updated 2026-04-29

Next Topic: Testing Library for Web Components Cheat Sheet

🧠Study flashcards on this topic120 cards · spaced repetition→

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, 120 flashcards. 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

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

Table 1: OpenAPI Document Structure

These are the top-level fields that make up the skeleton of every OpenAPI document. Only openapi and info are strictly required, but in practice you'll always have paths (the endpoints) and components (the reusable building blocks the rest of the document points back to). The newer entries—webhooks and $self—reflect how the spec has grown to describe APIs that push events outward and live across multiple files.

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.
security	`security:` `- apiKey: []`	• Global security requirements applied to all operations unless overridden at the operation level • references schemes in `components/securitySchemes`.
webhooks	`webhooks:` `newUser:` `post: {...}`	• OpenAPI 3.1+ feature for defining out-of-band requests the API sends to client-provided URLs when events occur • distinct from operation callbacks.
tags	`tags:` `- name: Users` `description: User management`	• Array of tag objects used to group operations in documentation • operations reference tags for logical organization.
externalDocs	`externalDocs:` `url: https://docs.example.com`	Link to external documentation providing additional context or details about the API.
$self	`$self: https://example.com/api/openapi.yaml`	• OpenAPI 3.2+. Declares the document's canonical URI and base URI for resolving all relative `$ref`s • makes multi-file API descriptions portable regardless of where files are hosted.

Table 2: Info Object Fields

The info block is your API's cover page—the metadata documentation tools render at the top before a single endpoint appears. Only title and version are mandatory, and the version here describes your API, not the OpenAPI spec it conforms to (a distinction that trips up newcomers). The rest fill in contact details, licensing, and the descriptions readers actually see.

Field	Example	Description
title	`title: Pet Store API`	Required. Human-readable name of the API displayed prominently in documentation.

The rest of this section is part of the full cheat sheet

Table 3: HTTP Methods (Operations)

Each verb you nest under a path defines one operation, and the verb itself carries meaning that clients, caches, and proxies rely on. Two properties matter most: whether a method is safe (no side effects) and idempotent (repeating it changes nothing further). GET is both; POST is neither—and the new 3.2 QUERY method finally gives you a safe, idempotent way to send a request body for searches too complex to fit in a URL.

Method	Example	Description
GET	`get:` `summary: List users`	• Retrieve/read a resource or collection • idempotent and safe — no side effects; multiple identical requests yield the same result.

The rest of this section is part of the full cheat sheet

Table 4: Path and Operation Fields

Inside each operation, these fields describe what it does and what it accepts. responses is the only required one—every operation must document at least one outcome—but operationId quietly does heavy lifting, since code generators turn it into SDK method names and AI agents use it as a tool name. The parameters, requestBody, and security fields define the inputs and access rules, while summary, tags, and deprecated shape how the operation reads in documentation.

Field	Example	Description
summary	`summary: Get user by ID`	Short, one-line description of the operation — displayed prominently in documentation.

The rest of this section is part of the full cheat sheet

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.
security	`security:` `- apiKey: []`	• Global security requirements applied to all operations unless overridden at the operation level • references schemes in `components/securitySchemes`.
webhooks	`webhooks:` `newUser:` `post: {...}`	• OpenAPI 3.1+ feature for defining out-of-band requests the API sends to client-provided URLs when events occur • distinct from operation callbacks.
tags	`tags:` `- name: Users` `description: User management`	• Array of tag objects used to group operations in documentation • operations reference tags for logical organization.
externalDocs	`externalDocs:` `url: https://docs.example.com`	Link to external documentation providing additional context or details about the API.
$self	`$self: https://example.com/api/openapi.yaml`	• OpenAPI 3.2+. Declares the document's canonical URI and base URI for resolving all relative `$ref`s • makes multi-file API descriptions portable regardless of where files are hosted.

Table 2: Info Object Fields

Field	Example	Description
title	`title: Pet Store API`	Required. Human-readable name of the API displayed prominently in documentation.

Table 3: HTTP Methods (Operations)

Method	Example	Description
GET	`get:` `summary: List users`	• Retrieve/read a resource or collection • idempotent and safe — no side effects; multiple identical requests yield the same result.

Table 4: Path and Operation Fields

Field	Example	Description
summary	`summary: Get user by ID`	Short, one-line description of the operation — displayed prominently in documentation.

Swagger/OpenAPI Cheat Sheet

Table 1: OpenAPI Document Structure

Table 2: Info Object Fields

Table 3: HTTP Methods (Operations)

Table 4: Path and Operation Fields

Swagger/OpenAPI Cheat Sheet

Table 1: OpenAPI Document Structure

Table 2: Info Object Fields

Table 3: HTTP Methods (Operations)

Table 4: Path and Operation Fields