Course contentsShow
← System Design
Lesson 1885 of 1,91945. API Design and VersioningFree lesson

API Documentation with OpenAPI/Swagger

Using OpenAPI specification to document endpoints, schemas, and enable interactive exploration.

API Documentation with OpenAPI/Swagger

What You'll Learn

You'll learn how to use OpenAPI specification to create machine-readable API documentation that serves as both a contract and an interactive exploration tool.

The Problem with Ad-Hoc Documentation

Imagine maintaining a manual describing every resource, endpoint, parameter, and response for your REST API—then keeping it updated as the API evolves. Traditional docs quickly become outdated and lack the ability to actually test the API directly from the documentation.

What is OpenAPI?

OpenAPI (formerly Swagger) is a specification language for describing RESTful APIs. It's a YAML or JSON document that formally defines:

  • Every endpoint path and HTTP method
  • Request parameters (path, query, headers, body)
  • Request and response schemas with data types
  • Authentication mechanisms
  • Error responses and status codes

Think of it as a blueprint that both humans and machines can read.

Core Structure

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

The Power of OpenAPI

Once you define your API in OpenAPI format:

  1. Auto-generate interactive docs (Swagger UI) where developers can make real API calls
  2. Generate client libraries in multiple languages automatically
  3. Enable API validation tools to ensure requests/responses match the spec
  4. Support contract-first design where you define the API before implementation

This bridges documentation, testing, and development into a single source of truth.

Key Takeaway: OpenAPI transforms API documentation from static text into a machine-readable contract that enables automatic tooling, interactive exploration, and enforces consistency between documentation and implementation.