Introduction

OpenAPI (formerly Swagger) is the standard for REST API documentation and design. It allows you to describe your API in a machine-readable format, enabling code generation, testing, and interactive documentation.

What is OpenAPI?

OpenAPI is a specification for describing REST APIs. It’s a YAML or JSON file that defines:

  • API endpoints
  • Request/response schemas
  • Authentication
  • Examples
  • Error responses

Basic OpenAPI Structure

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

Core Concepts

Paths and Operations

paths:
  /users:
    get:
      summary: Get all users
      operationId: getUsers
      responses:
        "200":
          description: Success
    post:
      summary: Create user
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "201":
          description: User created

  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User found

Components and Schemas

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: John Doe
        createdAt:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer

Request Bodies

POST Request Example

paths:
  /users:
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                name:
                  type: string
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

Authentication

API Key

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []

Bearer Token

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

paths:
  /users:
    get:
      security:
        - BearerAuth: []

Best Practices

✅ Do This

1. Use reusable schemas

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        email: { type: string }

    UserList:
      type: array
      items:
        $ref: "#/components/schemas/User"

2. Document all responses

responses:
  "200":
    description: Success
  "400":
    description: Bad request
  "401":
    description: Unauthorized
  "404":
    description: Not found
  "500":
    description: Internal server error

3. Add examples

content:
  application/json:
    schema:
      $ref: "#/components/schemas/User"
    example:
      id: 1
      email: user@example.com
      name: John Doe

4. Version your API

info:
  title: User API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1
    description: Production server

❌ Don’t Do This

1. Don’t skip error responses

# ❌ Missing error responses
responses:
  '200':
    description: Success

# ✅ Complete responses
responses:
  '200': { description: Success }
  '400': { description: Bad request }
  '500': { description: Server error }

2. Don’t use generic types

# ❌ Too generic
schema:
  type: object
  properties:
    data: { type: object }

# ✅ Specific schema
schema:
  $ref: '#/components/schemas/User'

Code Generation

Generate Client Code

# Generate TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated-client

Generate Server Code

# Generate Express server
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated-server

Tools and Resources

Use our tools:

Other tools:

  • Swagger Editor (online)
  • Swagger UI (documentation)
  • Postman (import OpenAPI)

Conclusion

OpenAPI enables:

Benefits:

  • Standardized API documentation
  • Code generation
  • Automated testing
  • Interactive documentation
  • Better developer experience

Key practices:

  • Define schemas first
  • Document all responses
  • Use examples
  • Version your API
  • Validate schemas

Next Steps