OpenAPI/Swagger Documentation

[KevinTrinhDev]

Auto-generate OpenAPI/Swagger docs from Zod schemas.\n\n- OpenAPI 3.1 spec auto-generated from route definitions\n- Swagger UI served at /docs endpoint\n- Request/response schema documentation\n- Authentication documentation\n- Export as JSON/YAML

[bad-antics]

Here's a complete OpenAPI/Swagger implementation with Zod schema integration:

1. Install Dependencies:

npm install @hono/swagger-ui @hono/zod-openapi zod-to-openapi

2. OpenAPI Config (lib/openapi.ts):

import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
import { swaggerUI } from '@hono/swagger-ui';

// Create OpenAPI-enabled Hono app
export const app = new OpenAPIHono();

// Serve Swagger UI
app.get('/docs', swaggerUI({ url: '/openapi.json' }));

// Serve OpenAPI spec
app.doc('/openapi.json', {
  openapi: '3.1.0',
  info: {
    title: 'DiscoLink API',
    version: '1.0.0',
    description: 'Discord integration API',
  },
  servers: [
    { url: 'http://localhost:3000', description: 'Development' },
    { url: 'https://api.discolink.app', description: 'Production' },
  ],
  tags: [
    { name: 'Auth', description: 'Authentication endpoints' },
    { name: 'Links', description: 'Link management' },
    { name: 'Users', description: 'User operations' },
  ],
});

3. Zod Schemas with OpenAPI Metadata (schemas/user.ts):

import { z } from '@hono/zod-openapi';

export const UserSchema = z.object({
  id: z.string().uuid().openapi({
    example: '123e4567-e89b-12d3-a456-426614174000',
  }),
  email: z.string().email().openapi({
    example: 'user@example.com',
  }),
  name: z.string().min(2).max(50).openapi({
    example: 'John Doe',
  }),
  createdAt: z.string().datetime().openapi({
    example: '2024-01-15T12:00:00Z',
  }),
}).openapi('User');

export const CreateUserSchema = UserSchema.omit({ 
  id: true, 
  createdAt: true 
}).openapi('CreateUser');

export const ErrorSchema = z.object({
  code: z.string(),
  message: z.string(),
}).openapi('Error');

4. Routes with OpenAPI Documentation (routes/users.ts):

import { createRoute, z } from '@hono/zod-openapi';
import { UserSchema, CreateUserSchema, ErrorSchema } from '../schemas/user';

export const getUsersRoute = createRoute({
  method: 'get',
  path: '/users',
  tags: ['Users'],
  summary: 'List all users',
  description: 'Returns paginated list of users',
  security: [{ bearerAuth: [] }],
  request: {
    query: z.object({
      page: z.coerce.number().min(1).default(1).openapi({
        example: 1,
      }),
      limit: z.coerce.number().min(1).max(100).default(20).openapi({
        example: 20,
      }),
    }),
  },
  responses: {
    200: {
      description: 'Successful response',
      content: {
        'application/json': {
          schema: z.object({
            data: z.array(UserSchema),
            pagination: z.object({
              page: z.number(),
              totalPages: z.number(),
              totalCount: z.number(),
            }),
          }),
        },
      },
    },
    401: {
      description: 'Unauthorized',
      content: {
        'application/json': { schema: ErrorSchema },
      },
    },
  },
});

export const createUserRoute = createRoute({
  method: 'post',
  path: '/users',
  tags: ['Users'],
  summary: 'Create a new user',
  request: {
    body: {
      content: {
        'application/json': { schema: CreateUserSchema },
      },
    },
  },
  responses: {
    201: {
      description: 'User created',
      content: {
        'application/json': { schema: UserSchema },
      },
    },
    400: {
      description: 'Validation error',
      content: {
        'application/json': { schema: ErrorSchema },
      },
    },
  },
});

5. Register Routes (index.ts):

import { app } from './lib/openapi';
import { getUsersRoute, createUserRoute } from './routes/users';

app.openapi(getUsersRoute, async (c) => {
  const { page, limit } = c.req.valid('query');
  // Implementation...
  return c.json({ data: [], pagination: { page, totalPages: 1, totalCount: 0 } });
});

app.openapi(createUserRoute, async (c) => {
  const body = c.req.valid('json');
  // Implementation...
  return c.json(newUser, 201);
});

export default app;

6. Auth Security Scheme:

app.openAPIRegistry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer',
  bearerFormat: 'JWT',
});

7. Export Spec as JSON/YAML:

// GET /openapi.json - auto-generated
// GET /openapi.yaml
app.get('/openapi.yaml', async (c) => {
  const spec = app.getOpenAPIDocument();
  return c.text(yaml.stringify(spec), 200, {
    'Content-Type': 'text/yaml',
  });
});

Features covered:

• OpenAPI 3.1 auto-generation from Zod
• Swagger UI at /docs
• Request/response documentation
• Auth documentation
• JSON/YAML export

[bad-antics]

Here's a complete OpenAPI/Swagger documentation setup with Zod schemas:

1. Install Dependencies:

npm install @asteasolutions/zod-to-openapi swagger-ui-express yaml
npm install -D @types/swagger-ui-express

2. OpenAPI Registry Setup (lib/openapi/registry.ts):

import { 
  OpenAPIRegistry,
  OpenApiGeneratorV31,
  extendZodWithOpenApi,
} from '@asteasolutions/zod-to-openapi';
import { z } from 'zod';

// Extend Zod with OpenAPI methods
extendZodWithOpenApi(z);

// Create registry
export const registry = new OpenAPIRegistry();

// Security schemes
registry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer',
  bearerFormat: 'JWT',
  description: 'JWT Authorization header',
});

registry.registerComponent('securitySchemes', 'apiKey', {
  type: 'apiKey',
  in: 'header',
  name: 'X-API-Key',
  description: 'API Key for external integrations',
});

// Common schemas
export const ErrorResponseSchema = z.object({
  success: z.literal(false),
  error: z.object({
    code: z.string(),
    message: z.string(),
    details: z.record(z.any()).optional(),
  }),
}).openapi('ErrorResponse');

export const PaginationSchema = z.object({
  page: z.number().int().positive(),
  limit: z.number().int().min(1).max(100),
  total: z.number().int().nonnegative(),
  totalPages: z.number().int().nonnegative(),
}).openapi('Pagination');

registry.register('ErrorResponse', ErrorResponseSchema);
registry.register('Pagination', PaginationSchema);

3. Route Documentation Helper (lib/openapi/route.ts):

import { RouteConfig, ZodRequestBody } from '@asteasolutions/zod-to-openapi';
import { z, ZodType } from 'zod';
import { registry } from './registry';

interface DocumentedRouteConfig {
  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
  path: string;
  summary: string;
  description?: string;
  tags: string[];
  request?: {
    params?: ZodType;
    query?: ZodType;
    body?: {
      content: ZodType;
      description?: string;
    };
  };
  responses: {
    [statusCode: number]: {
      description: string;
      content?: ZodType;
    };
  };
  security?: ('bearerAuth' | 'apiKey')[];
}

export function documentRoute(config: DocumentedRouteConfig) {
  const routeConfig: RouteConfig = {
    method: config.method,
    path: config.path,
    summary: config.summary,
    description: config.description,
    tags: config.tags,
    request: {},
    responses: {},
  };

  // Request params
  if (config.request?.params) {
    routeConfig.request!.params = config.request.params;
  }

  // Request query
  if (config.request?.query) {
    routeConfig.request!.query = config.request.query;
  }

  // Request body
  if (config.request?.body) {
    routeConfig.request!.body = {
      content: {
        'application/json': {
          schema: config.request.body.content,
        },
      },
      description: config.request.body.description,
    };
  }

  // Responses
  Object.entries(config.responses).forEach(([statusCode, response]) => {
    routeConfig.responses[statusCode] = {
      description: response.description,
    };

    if (response.content) {
      routeConfig.responses[statusCode].content = {
        'application/json': {
          schema: response.content,
        },
      };
    }
  });

  // Security
  if (config.security) {
    routeConfig.security = config.security.map(scheme => ({ [scheme]: [] }));
  }

  registry.registerPath(routeConfig);
}

4. Document Routes (routes/users.docs.ts):

import { z } from 'zod';
import { documentRoute } from '../lib/openapi/route';
import { ErrorResponseSchema, PaginationSchema } from '../lib/openapi/registry';

// User schemas with OpenAPI metadata
export const UserSchema = z.object({
  id: z.string().uuid().openapi({ example: '550e8400-e29b-41d4-a716-446655440000' }),
  email: z.string().email().openapi({ example: 'user@example.com' }),
  name: z.string().min(1).max(100).openapi({ example: 'John Doe' }),
  role: z.enum(['user', 'admin', 'moderator']).openapi({ example: 'user' }),
  createdAt: z.string().datetime().openapi({ example: '2024-01-24T12:00:00Z' }),
}).openapi('User');

export const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  password: z.string().min(8).max(100).openapi({ 
    example: 'SecureP@ss123',
    description: 'Password must be at least 8 characters',
  }),
  role: z.enum(['user', 'admin', 'moderator']).default('user').optional(),
}).openapi('CreateUser');

export const UpdateUserSchema = z.object({
  email: z.string().email().optional(),
  name: z.string().min(1).max(100).optional(),
}).openapi('UpdateUser');

export const UserListSchema = z.object({
  success: z.literal(true),
  data: z.array(UserSchema),
  pagination: PaginationSchema,
}).openapi('UserList');

// Document GET /users
documentRoute({
  method: 'get',
  path: '/api/users',
  summary: 'List all users',
  description: 'Retrieve a paginated list of all users. Requires authentication.',
  tags: ['Users'],
  security: ['bearerAuth'],
  request: {
    query: z.object({
      page: z.coerce.number().int().positive().default(1).openapi({ example: 1 }),
      limit: z.coerce.number().int().min(1).max(100).default(20).openapi({ example: 20 }),
      search: z.string().optional().openapi({ example: 'john' }),
      role: z.enum(['user', 'admin', 'moderator']).optional(),
    }),
  },
  responses: {
    200: {
      description: 'List of users',
      content: UserListSchema,
    },
    401: {
      description: 'Unauthorized',
      content: ErrorResponseSchema,
    },
  },
});

// Document GET /users/:id
documentRoute({
  method: 'get',
  path: '/api/users/{id}',
  summary: 'Get user by ID',
  tags: ['Users'],
  security: ['bearerAuth'],
  request: {
    params: z.object({
      id: z.string().uuid(),
    }),
  },
  responses: {
    200: {
      description: 'User details',
      content: z.object({
        success: z.literal(true),
        data: UserSchema,
      }),
    },
    404: {
      description: 'User not found',
      content: ErrorResponseSchema,
    },
  },
});

// Document POST /users
documentRoute({
  method: 'post',
  path: '/api/users',
  summary: 'Create a new user',
  tags: ['Users'],
  security: ['bearerAuth'],
  request: {
    body: {
      content: CreateUserSchema,
      description: 'User creation data',
    },
  },
  responses: {
    201: {
      description: 'User created successfully',
      content: z.object({
        success: z.literal(true),
        data: UserSchema,
      }),
    },
    400: {
      description: 'Validation error',
      content: ErrorResponseSchema,
    },
    409: {
      description: 'Email already exists',
      content: ErrorResponseSchema,
    },
  },
});

// Document PATCH /users/:id
documentRoute({
  method: 'patch',
  path: '/api/users/{id}',
  summary: 'Update a user',
  tags: ['Users'],
  security: ['bearerAuth'],
  request: {
    params: z.object({ id: z.string().uuid() }),
    body: {
      content: UpdateUserSchema,
      description: 'Fields to update',
    },
  },
  responses: {
    200: {
      description: 'User updated',
      content: z.object({
        success: z.literal(true),
        data: UserSchema,
      }),
    },
    404: {
      description: 'User not found',
      content: ErrorResponseSchema,
    },
  },
});

// Document DELETE /users/:id
documentRoute({
  method: 'delete',
  path: '/api/users/{id}',
  summary: 'Delete a user',
  tags: ['Users'],
  security: ['bearerAuth'],
  request: {
    params: z.object({ id: z.string().uuid() }),
  },
  responses: {
    204: {
      description: 'User deleted',
    },
    404: {
      description: 'User not found',
      content: ErrorResponseSchema,
    },
  },
});

5. Generate OpenAPI Spec (lib/openapi/generator.ts):

import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
import { registry } from './registry';
import YAML from 'yaml';

// Import all route docs
import '../routes/users.docs';
import '../routes/auth.docs';
// ... import other route docs

export function generateOpenAPISpec() {
  const generator = new OpenApiGeneratorV31(registry.definitions);
  
  return generator.generateDocument({
    openapi: '3.1.0',
    info: {
      title: 'DiscoLink API',
      version: '1.0.0',
      description: 'DiscoLink REST API documentation',
      contact: {
        name: 'API Support',
        email: 'support@discolink.io',
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT',
      },
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: 'Development server',
      },
      {
        url: 'https://api.discolink.io',
        description: 'Production server',
      },
    ],
    tags: [
      { name: 'Auth', description: 'Authentication endpoints' },
      { name: 'Users', description: 'User management' },
      { name: 'Links', description: 'Link management' },
    ],
  });
}

export function getOpenAPIJSON(): string {
  return JSON.stringify(generateOpenAPISpec(), null, 2);
}

export function getOpenAPIYAML(): string {
  return YAML.stringify(generateOpenAPISpec());
}

6. Swagger UI Setup (routes/docs.ts):

import { Router, Request, Response } from 'express';
import swaggerUi from 'swagger-ui-express';
import { generateOpenAPISpec, getOpenAPIJSON, getOpenAPIYAML } from '../lib/openapi/generator';

const router = Router();

// Swagger UI
const swaggerOptions = {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'DiscoLink API Docs',
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
    filter: true,
    tryItOutEnabled: true,
  },
};

router.use('/docs', swaggerUi.serve);
router.get('/docs', swaggerUi.setup(generateOpenAPISpec(), swaggerOptions));

// Export JSON spec
router.get('/docs/openapi.json', (req: Request, res: Response) => {
  res.setHeader('Content-Type', 'application/json');
  res.setHeader('Content-Disposition', 'attachment; filename=openapi.json');
  res.send(getOpenAPIJSON());
});

// Export YAML spec
router.get('/docs/openapi.yaml', (req: Request, res: Response) => {
  res.setHeader('Content-Type', 'application/x-yaml');
  res.setHeader('Content-Disposition', 'attachment; filename=openapi.yaml');
  res.send(getOpenAPIYAML());
});

// ReDoc alternative (lighter UI)
router.get('/redoc', (req: Request, res: Response) => {
  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <title>DiscoLink API Docs</title>
        <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
        <style>body { margin: 0; padding: 0; }</style>
      </head>
      <body>
        <redoc spec-url='/docs/openapi.json'></redoc>
        <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
      </body>
    </html>
  `);
});

export default router;

7. Main App Integration (app.ts):

import express from 'express';
import docsRouter from './routes/docs';
import userRoutes from './routes/users';

const app = express();

app.use(express.json());

// API routes
app.use('/api', userRoutes);

// Documentation (only in non-production or with flag)
if (process.env.NODE_ENV !== 'production' || process.env.ENABLE_DOCS === 'true') {
  app.use(docsRouter);
}

export default app;

8. Access Points:

• Swagger UI: http://localhost:3000/docs
• ReDoc: http://localhost:3000/redoc
• OpenAPI JSON: http://localhost:3000/docs/openapi.json
• OpenAPI YAML: http://localhost:3000/docs/openapi.yaml

Complete auto-generated OpenAPI 3.1 docs from Zod schemas with Swagger UI and export options!