OpenAPI & Swagger Cheat Sheet
Quick reference for the OpenAPI 3.1 specification: paths, operations, schemas, components, security, and spec organization.
OpenAPI (formerly Swagger) is a machine-readable specification for REST APIs, written in JSON or YAML. OpenAPI 3.1 uses JSON Schema 2020-12 for schemas and adds webhooks. The root document has four top-level required fields: openapi, info, paths, and (optionally) components.
Top-Level Structure
openapi: 3.1.0
info:
title: Pet Store API
version: 1.0.0
description: Example API
servers:
- url: https://api.example.com/v1
paths: {}
components: {}
| Field | Required | Purpose |
|---|---|---|
openapi | Yes | Specification version (3.0.3, 3.1.0) |
info.title | Yes | API name |
info.version | Yes | API version string |
servers | No | Base URLs; defaults to / |
paths | Yes | Operations grouped by URL path |
components | No | Reusable schemas, parameters, security schemes |
tags | No | Logical grouping for operations |
webhooks | No | Outbound events (3.1+) |
Paths & Operations
Each path maps to an HTTP method object. summary and description are shown in docs; operationId must be unique and becomes the function name in generated SDKs.
paths:
/pets:
get:
summary: List pets
operationId: listPets
parameters:
- $ref: '#/components/parameters/limit'
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
$ref: '#/components/schemas/Pets'
post:
summary: Create a pet
operationId: createPet
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
responses:
'201':
description: Created pet
Parameters
Parameters appear in four locations: query, header, path, cookie. Path parameters must also appear in the path string wrapped in braces (/pets/{id}).
| Field | Purpose |
|---|---|
name | Parameter name |
in | Location: query, header, path, cookie |
required | true for path parameters |
schema | Data type; type: string, type: integer, etc. |
style | Serialization (query defaults form, path simple) |
example / examples | Sample value for docs |
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
Schemas & Components
Schemas follow JSON Schema. Reuse them through components.schemas and $ref to avoid duplication.
components:
schemas:
Pet:
type: object
required: [id, name]
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
status:
type: string
enum: [available, pending, sold]
Pets:
type: array
items:
$ref: '#/components/schemas/Pet'
Security Schemes
Define components.securitySchemes once, then apply security globally or per-operation (empty security: [] disables it for an operation).
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- bearerAuth: []
Common Pitfalls
[!WARNING] In OpenAPI 3.x, request bodies live in
requestBody— thebody/formDataparameters of Swagger 2.0 are gone. Migrating 2.0 → 3.0 requires rewriting them.
[!TIP] Prefer
components+$refover inline duplication; most tools generate SDKs and docs straight from the spec, so naming consistency matters.