# Mern API Docs

> Generate OpenAPI documentation from Zod schemas and API routes. Use when this capability is needed.

- Skill: `tomevault-io/mern-api-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/mern-api-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mern-api-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/mern-api-docs

---


## Purpose
Generate and serve OpenAPI (Swagger) documentation derived from Zod schemas and Next.js API routes.

## Arguments
- `--serve` — Start Swagger UI at `/api/docs`
- `--export <path>` — Export OpenAPI spec to file (default: `openapi.json`)
- (no args) — Generate spec and report endpoints documented

## What gets created

```
apps/web/
├── app/api/docs/route.ts           # Swagger UI endpoint
├── src/lib/openapi.ts              # OpenAPI spec generator
└── openapi.json                    # Generated spec (if --export)
```

## How it works

1. **Scans** `packages/shared/schemas/` for Zod schemas
2. **Scans** `apps/web/src/app/api/` for route handlers
3. **Extracts** request/response types from Zod schemas
4. **Generates** OpenAPI 3.0 spec with:
   - Endpoints from file structure
   - Request bodies from `Create*Schema`
   - Response schemas from `*ResponseSchema`
   - Query params from `*QuerySchema`
   - Path params from `[id]` segments

## Schema conventions for docs

```typescript
// packages/shared/schemas/todo-item.ts

/** @description Create a new todo item */
export const CreateTodoItemSchema = z.object({
  /** @description Item title (required) */
  title: z.string().min(1).max(200),
  /** @description Optional description */
  description: z.string().optional(),
});

/** @description Todo item response */
export const TodoItemSchema = z.object({
  id: z.string(),
  title: z.string(),
  // ...
});
```

JSDoc comments become OpenAPI descriptions.

## Swagger UI

When `--serve` is used, Swagger UI is available at `/api/docs`:
- Interactive API explorer
- Try-it-out functionality (with auth)
- Schema visualization

## Workflow
1. Ensure schemas follow naming conventions
2. Run skill to generate/update spec
3. Review generated documentation
4. Optionally serve Swagger UI

## Output
- Endpoints documented count
- Schemas extracted count
- Missing documentation warnings
- Spec file location (if exported)

## Reference
For setup and customization, see `reference/mern-api-docs-reference.md`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/edfenton) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->