OpenAPI Specification: Document and Auto-Generate API Mocks

OpenAPI solves this by having one source of truth.

OpenAPI Specification Basics

An OpenAPI spec is typically a YAML or JSON file that describes:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Key Components

Info

Basic metadata about your API:

• Title and description
• Version number
• Contact information
• License information

Paths

All the endpoints in your API. For each path:

• HTTP method (GET, POST, etc.)
• Summary and description
• Parameters (path, query, header)
• Request body schema
• Response schemas
• Security requirements

Schemas

Define the structure of request/response objects:

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

Generating Swagger UI Documentation

Swagger UI automatically generates interactive documentation from your OpenAPI spec.

Tools that generate Swagger UI:

• Swagger UI - Official tool
• ReDoc - Beautiful alternative
• Scalar - Modern documentation
• Stoplight Elements - Hosted documentation

Auto-Generating Mocks with Prism

Prism is a mock server that reads OpenAPI specs and generates mock responses:

npm install -g @stoplight/prism-cli
prism mock api.yaml

Now you have a working mock server without writing any code!

Code-First vs Spec-First

Spec-First Approach

1. Write the OpenAPI spec
2. Generate code and mocks
3. Implement the specification

Advantages: Single source of truth, documentation always in sync, teams can work in parallel, mock servers available immediately

Code-First Approach

1. Write API code
2. Generate OpenAPI spec from code
3. Generate documentation

Advantages: Familiar workflow, don't write specs twice, real behavior is documented

Generating SDKs from OpenAPI

Tools like OpenAPI Generator can create SDKs automatically:

openapi-generator-cli generate \
  -i api.yaml \
  -g javascript \
  -o ./generated-sdk

Now clients can use your SDK with full type safety.

Benefits Summary

• Documentation - Auto-generated from spec
• Mocking - Immediate mock servers
• SDK Generation - Client libraries for free
• Testing - Contract-based validation
• Onboarding - Interactive API explorer
• Consistency - All teams follow same spec

Conclusion

OpenAPI is the standard for API documentation. Whether you're building a small API or managing an API platform with dozens of endpoints, using OpenAPI will save you time and keep your documentation always in sync with reality.