Let’s through the process of adding OpenAPI documentation to a TypeScript Express server using Zod for validation.

Extend Zod Schemas with OpenAPI Metadata

Create a new file openapi.ts that will convert your Zod schemas to OpenAPI format:

import { extendZodWithOpenApi, generateSchema } from '@anatine/zod-openapi';
import { OpenAPIObject } from 'openapi3-ts/oas31';
import { z } from 'zod';
import * as schemas from './your-schemas'; // Import your Zod schemas

extendZodWithOpenApi(z);

// Define TaskSchema with OpenAPI metadata
const TaskSchema = schemas.TaskSchema.openapi({
  description: 'A task item',
  example: {
    id: 1,
    title: 'Complete OpenAPI integration',
    description: 'Add OpenAPI specs to the tasks API',
    completed: false,
  },
});

const TasksSchema = schemas.TasksSchema.openapi({
  description: 'A collection of task items',
});

const NewTaskSchema = schemas.NewTaskSchema.openapi({
  description: 'Data required to create a new task',
  example: {
    title: 'Create a new task',
    description: 'This is a new task to be created',
  },
});

const UpdateTaskSchema = schemas.UpdateTaskSchema.openapi({
  description: 'Data for updating an existing task',
  example: {
    title: 'Updated task title',
    description: 'Updated task description',
    completed: true,
  },
});

Define the OpenAPI Document

Add the full OpenAPI specification to your openapi.ts file:

export const openApiDocument: OpenAPIObject = {
  openapi: '3.1.0',
  info: {
    title: 'Tasks API',
    version: '1.0.0',
    description: 'API for managing tasks',
    contact: {
      name: 'Steve Kinney',
      email: 'hello@stevekinney.net',
    },
  },
  paths: {
    '/tasks': {
      get: {
        tags: ['Tasks'],
        summary: 'Get all tasks',
        description: 'Retrieve all tasks, optionally filtered by completion status',
        parameters: [
          {
            name: 'completed',
            in: 'query',
            required: false,
            schema: {
              type: 'boolean',
            },
            description: 'Filter tasks by completion status',
          },
        ],
        responses: {
          '200': {
            description: 'List of tasks',
            content: {
              'application/json': {
                schema: generateSchema(TasksSchema),
              },
            },
          },
          '500': {
            description: 'Server error',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
        },
      },
      post: {
        tags: ['Tasks'],
        summary: 'Create a new task',
        description: 'Add a new task to the database',
        requestBody: {
          content: {
            'application/json': {
              schema: generateSchema(NewTaskSchema),
            },
          },
          required: true,
        },
        responses: {
          '201': {
            description: 'Task created successfully',
          },
          '400': {
            description: 'Invalid input',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
          '500': {
            description: 'Server error',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
        },
      },
    },
    '/tasks/{id}': {
      get: {
        tags: ['Tasks'],
        summary: 'Get a task by ID',
        description: 'Retrieve a single task by its ID',
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            schema: {
              type: 'integer',
            },
            description: 'ID of the task to retrieve',
          },
        ],
        responses: {
          '200': {
            description: 'Task found',
            content: {
              'application/json': {
                schema: generateSchema(TaskSchema),
              },
            },
          },
          '404': {
            description: 'Task not found',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
          '500': {
            description: 'Server error',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
        },
      },
      put: {
        tags: ['Tasks'],
        summary: 'Update a task',
        description: 'Update an existing task by its ID',
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            schema: {
              type: 'integer',
            },
            description: 'ID of the task to update',
          },
        ],
        requestBody: {
          content: {
            'application/json': {
              schema: generateSchema(UpdateTaskSchema),
            },
          },
          required: true,
        },
        responses: {
          '200': {
            description: 'Task updated successfully',
          },
          '404': {
            description: 'Task not found',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
          '400': {
            description: 'Invalid input',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
          '500': {
            description: 'Server error',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
        },
      },
      delete: {
        tags: ['Tasks'],
        summary: 'Delete a task',
        description: 'Delete a task by its ID',
        parameters: [
          {
            name: 'id',
            in: 'path',
            required: true,
            schema: {
              type: 'integer',
            },
            description: 'ID of the task to delete',
          },
        ],
        responses: {
          '200': {
            description: 'Task deleted successfully',
          },
          '404': {
            description: 'Task not found',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
          '500': {
            description: 'Server error',
            content: {
              'application/json': {
                schema: generateSchema(ErrorResponseSchema),
              },
            },
          },
        },
      },
    },
  },
  components: {
    schemas: {
      Task: generateSchema(TaskSchema),
      Tasks: generateSchema(TasksSchema),
      NewTask: generateSchema(NewTaskSchema),
      UpdateTask: generateSchema(UpdateTaskSchema),
      ErrorResponse: generateSchema(ErrorResponseSchema),
    },
  },
};

And then integrate with your Express server:

// server.ts
import express from 'express';
import swaggerUi from 'swagger-ui-express';
import { openApiDocument } from './openapi';

export async function createServer() {
  const app = express();
  app.use(express.json());

  // Serve OpenAPI docs
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openApiDocument));

  // Expose OpenAPI spec as JSON
  app.get('/openapi.json', (req, res) => {
    res.json(openApiDocument);
  });

  // Your existing routes...

  return app;
}

Accessessing the Documentation

Once implemented, you can access:

• Interactive API documentation at: /api-docs
• Raw OpenAPI JSON specification at: /openapi.json