⚡ OpenAPI / Swagger Quick Ref

Structure Overview

Root fields, info, servers, tags

Path Definitions

CRUD operations, examples

Parameters

Path, query, header, cookie

Request Body

JSON, form data, file uploads

Responses

Status codes, schemas, headers

Authentication

Bearer, API key, OAuth2

Components

Reusable schemas & refs

Full Example

Complete spec template

Structure Overview OpenAPI 3.0

The root structure of an OpenAPI 3.0 document. Every spec starts with openapi, info, and paths.

Minimal Spec
openapi: '3.0.3'
info:
  title: My API
  description: API description here
  version: '1.0.0'
  contact:
    name: Dev Team
    email: dev@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:3000/v1
    description: Development

tags:
  - name: users
    description: User management
  - name: products
    description: Product catalog

paths: {}
External Docs & Extensions
externalDocs:
  url: https://docs.example.com
  description: Full documentation

# Vendor extensions (x- prefix)
x-api-id: my-api-v1
x-logo: https://example.com/logo.png
Path Definitions

Define endpoints under paths with HTTP methods. Each operation needs at least a summary and responses.

CRUD Operations
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [users]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Success

    post:
      summary: Create user
      operationId: createUser
      tags: [users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Created

  /users/{userId}:
    get:
      summary: Get user by ID
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success

    put:
      summary: Update user
      operationId: updateUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
      responses:
        '200':
          description: Updated

    delete:
      summary: Delete user
      operationId: deleteUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
Path with Query & Common Params
/products:
  get:
    summary: List products
    parameters:
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sort
        in: query
        schema:
          type: string
          enum: [name, price, created_at]
          default: created_at
      - name: order
        in: query
        schema:
          type: string
          enum: [asc, desc]
          default: desc
    responses:
      '200':
        description: Paginated product list
Parameters

Four parameter locations: path, query, header, cookie. Parameters can be defined inline or referenced from components.

Path Parameters
# Path params are ALWAYS required
parameters:
  - name: userId
    in: path
    required: true
    description: Unique user identifier
    schema:
      type: string
      pattern: '^[a-zA-Z0-9-]+$'
      example: usr_abc123

  - name: orderId
    in: path
    required: true
    schema:
      type: integer
      example: 42
Query Parameters
parameters:
  - name: search
    in: query
    description: Search term
    schema:
      type: string
      minLength: 1
      maxLength: 200

  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]

  - name: include_deleted
    in: query
    schema:
      type: boolean
      default: false

  - name: tags
    in: query
    description: Filter by tags (comma-separated)
    style: form
    explode: false
    schema:
      type: array
      items:
        type: string
Header Parameters
parameters:
  - name: X-Request-ID
    in: header
    description: Client request ID for tracing
    schema:
      type: string
      format: uuid

  - name: X-Rate-Limit-Token
    in: header
    required: true
    schema:
      type: string

  - name: Accept-Language
    in: header
    schema:
      type: string
      default: en-US
Cookie Parameters
parameters:
  - name: session_id
    in: cookie
    description: Session cookie
    required: true
    schema:
      type: string

  - name: prefs
    in: cookie
    schema:
      type: string
      example: theme=dark;lang=en
Shared / Reusable Parameters
# Define in components/parameters
components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

# Reference in paths
paths:
  /items:
    get:
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
Request Body

Define payloads with content type negotiation. Use requestBody for POST, PUT, PATCH operations.

JSON Request Body
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required: [name, email]
        properties:
          name:
            type: string
            minLength: 1
            maxLength: 100
          email:
            type: string
            format: email
          role:
            type: string
            enum: [admin, editor, viewer]
            default: viewer
      examples:
        admin:
          summary: Admin user
          value:
            name: Jane Doe
            email: jane@example.com
            role: admin
        viewer:
          summary: Viewer user
          value:
            name: John Smith
            email: john@example.com
Form Data & File Upload
# URL-encoded form
requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          username:
            type: string
          password:
            type: string
            format: password

# Multipart (file upload)
requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            format: binary
          description:
            type: string
          tags:
            type: array
            items:
              type: string
Inline vs $ref Schema
# Inline schema
requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          id:
            type: integer

# Referenced schema (preferred for reuse)
requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/UserInput'
Responses

Define expected responses per status code. Include description, schema, headers, and examples.

Standard Response Patterns
responses:
  '200':
    description: Successful response
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/User'
            meta:
              $ref: '#/components/schemas/Pagination'
        example:
          data:
            - id: 1
              name: Jane
              email: jane@example.com
          meta:
            page: 1
            total: 42

  '201':
    description: Resource created
    headers:
      Location:
        description: URI of the new resource
        schema:
          type: string

  '204':
    description: No content (successful delete)

  '400':
    description: Bad request
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'

  '401':
    description: Unauthorized

  '404':
    description: Not found

  '500':
    description: Internal server error
Response Schema Patterns
# Simple object
schema:
  $ref: '#/components/schemas/User'

# Array response
schema:
  type: array
  items:
    $ref: '#/components/schemas/User'

# Paginated wrapper
schema:
  type: object
  properties:
    items:
      type: array
      items:
        $ref: '#/components/schemas/User'
    total:
      type: integer
    has_more:
      type: boolean

# OneOf / AllOf / AnyOf
schema:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
Authentication

Define security schemes in components/securitySchemes, then apply globally or per-operation.

Bearer Token (JWT)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your JWT token

# Apply globally
security:
  - BearerAuth: []
API Key
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key

    ApiKeyCookie:
      type: apiKey
      in: cookie
      name: api_key
OAuth2 Flows
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          refreshUrl: https://auth.example.com/refresh
          scopes:
            read: Read access
            write: Write access
            admin: Full admin access
        clientCredentials:
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
        implicit:
          authorizationUrl: https://auth.example.com/authorize
          scopes:
            read: Read access
        password:
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access
Applying Security
# Global (applies to ALL operations)
security:
  - BearerAuth: []

# Override per-operation
paths:
  /public/health:
    get:
      security: []   # No auth needed

  /admin/users:
    get:
      security:
        - OAuth2: [admin]

  /articles:
    get:
      security:
        - BearerAuth: []
        - ApiKeyHeader: []  # Either works
Components

Reusable schemas, responses, parameters, and more under components.

Reusable Schemas
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, editor, viewer]
        created_at:
          type: string
          format: date-time
          readOnly: true
      required: [id, name, email]

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          default: viewer

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
Schema Composition (allOf / oneOf / anyOf)
# Inheritance with allOf
AdminUser:
  allOf:
    - $ref: '#/components/schemas/User'
    - type: object
      properties:
        permissions:
          type: array
          items:
            type: string

# Polymorphism with oneOf + discriminator
Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: pet_type
    mapping:
      cat: '#/components/schemas/Cat'
      dog: '#/components/schemas/Dog'

# anyOf (at least one must match)
SearchResult:
  anyOf:
    - $ref: '#/components/schemas/User'
    - $ref: '#/components/schemas/Product'
Data Types Quick Ref
# Primitives
type: string
type: integer       # 32-bit
type: number        # float/double
type: boolean
type: array
type: object

# Common string formats
format: date          # YYYY-MM-DD
format: date-time     # ISO 8601
format: email
format: uri
format: uuid
format: password      # Hint for UI tools
format: binary        # File data
format: byte          # Base64

# Numeric constraints
minimum: 0
maximum: 100
exclusiveMinimum: true
multipleOf: 0.01

# String constraints
minLength: 1
maxLength: 255
pattern: '^[A-Z]{2,4}$'
Full Example

A complete, self-contained OpenAPI 3.0 spec you can copy and adapt.

Complete API Spec
openapi: '3.0.3'
info:
  title: Pet Store API
  description: A sample pet store API
  version: '1.0.0'
  contact:
    name: API Support
    email: support@petstore.com

servers:
  - url: https://api.petstore.com/v1

tags:
  - name: pets
    description: Pet operations

security:
  - BearerAuth: []

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags: [pets]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'

    post:
      summary: Create a pet
      operationId: createPet
      tags: [pets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetInput'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

  /pets/{petId}:
    get:
      summary: Get a pet by ID
      operationId: getPet
      tags: [pets]
      parameters:
        - $ref: '#/components/parameters/PetId'
      responses:
        '200':
          description: A pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '404':
          description: Pet not found

    delete:
      summary: Delete a pet
      operationId: deletePet
      tags: [pets]
      parameters:
        - $ref: '#/components/parameters/PetId'
      responses:
        '204':
          description: Pet deleted

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    PetId:
      name: petId
      in: path
      required: true
      schema:
        type: string

  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string
        tag:
          type: string
        status:
          type: string
          enum: [available, sold]

    PetInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
        tag:
          type: string

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
        message:
          type: string