Comprehensive Swagger/OpenAPI Cheatsheet

Introduction

Swagger, now part of the OpenAPI Initiative, is a powerful set of tools for designing, building, documenting, and consuming RESTful APIs. This cheatsheet covers OpenAPI Specification 3.0, which is the latest major version.

Basic Structure

A basic OpenAPI 3.0 document has the following structure:

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:    
              schema:
                type: array
                items:
                  type: string

Info Object

The info object contains API metadata:

info:
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts
  version: 1.0.0
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

Servers

Define one or more API servers:

servers:
  - url: https://development.gigantic-server.com/v1
    description: Development server
  - url: https://staging.gigantic-server.com/v1
    description: Staging server
  - url: https://api.gigantic-server.com/v1
    description: Production server

Paths

Paths define the endpoints of your API and the operations available on those endpoints:

paths:
  /users:
    get:
      summary: Returns a list of users.
      responses:
        '200':
          description: Successful response
    post:
      summary: Creates a new user.
      responses:
        '201':
          description: Created
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return.
          schema:
            type: integer
      responses:
        '200':
          description: Successful response

Parameters

Parameters can be passed via path, query string, headers, and cookies:

parameters:
  - in: path
    name: userId
    required: true
    schema:
      type: integer
  - in: query
    name: limit
    schema:
      type: integer
  - in: header
    name: X-Request-ID
    schema:
      type: string
  - in: cookie
    name: session_id
    schema:
      type: string

Request Body

Describe the request body for POST, PUT, and PATCH operations:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        properties:
          name:
            type: string
          email:
            type: string

Responses

Define possible responses for each operation:

responses:
  '200':
    description: Successful response
    content:
      application/json:
        schema:
          type: array
          items:
            type: string
  '400':
    description: Bad request
  '404':
    description: Resource not found

Schema

Use JSON Schema vocabulary to describe request and response payloads:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name

Components

Reusable objects for different aspects of the API:

components:
  schemas:
    User: 
      type: object
      properties:
        id: 
          type: integer
        name: 
          type: string
  responses:
    NotFound:
      description: Resource not found
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      schema:
        type: integer
  examples:
    user:
      value:
        id: 1
        name: John Doe
  requestBodies:
    UserBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
  headers:
    X-Rate-Limit:
      description: calls per hour allowed by the user
      schema:
        type: integer
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

Security

Define security requirements:

security:
  - BasicAuth: []
  - ApiKeyAuth: []
  - OAuth2:
    - read
    - write

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access

Tags

Group operations with tags:

tags:
  - name: users
    description: User operations
  - name: products
    description: Product operations

paths:
  /users:
    get:
      tags:
        - users
      # ...
  /products:
    get:
      tags:
        - products
      # ...

External Docs

Link to external documentation:

externalDocs:
  description: API Documentation
  url: https://docs.example.com