@wuyuchentr/api-doc-generator

Generate OpenAPI 3.0 docs and Swagger UI from JSDoc comments. Zero dependencies.

Supports Express, Fastify, Koa route patterns. Parses @get, @post, @param, @returns, etc.

Install

npm install -g @wuyuchentr/api-doc-generator

Usage

CLI

# Scan ./src and output to ./docs/
npx api-doc-generator ./src

# Custom output dir
npx api-doc-generator ./routes -o ./api-docs --title "My API"

# Open the generated Swagger UI
open docs/index.html

API

const { generate, parseFile, buildSpec, renderUI } = require('@wuyuchentr/api-doc-generator');

// Scan and generate
const result = await generate('./src');
result.writeJSON('./openapi.json');
result.writeUI('./index.html');

// Parse a single file
const eps = parseFile('routes/users.js');

// Build from parsed endpoints
const spec = buildSpec(eps, { title: 'My API' });
const html = renderUI(spec);

JSDoc format

/**
 * Get user by ID
 * @get /users/:id
 * @param {number} id - 用户ID
 * @returns {User}
 * @summary Retrieve a single user
 * @tag Users
 * @auth Bearer
 */
function getUser(req, res) { ... }

/**
 * Create a new user
 * @post /users
 * @body {CreateUserDto} body - User data
 * @returns {User}
 * @tag Users
 */
function createUser(req, res) { ... }

Supported tags

| Tag | Description | |-----|-------------| | @get /path | HTTP method + path | | @post /path | | | @put /path | | | @delete /path | | | @patch /path | | | @param {type} name - desc | Path or query parameter | | @body {type} name - desc | Request body | | @returns {type} desc | Response | | @summary text | Short summary | | @tag Name | Tag group | | @auth Bearer | Security scheme |

Type support

| Type | OpenAPI mapping | |------|----------------| | string | { type: string } | | number | { type: number } | | boolean | { type: boolean } | | integer | { type: integer } | | date | { type: string, format: date } | | email | { type: string, format: email } | | uuid | { type: string, format: uuid } | | Array<Type> | { type: array, items: Type } | | User | { $ref: '#/.../User' } (capitalized → reference) |

Output

• openapi.json — OpenAPI 3.0 spec
• index.html — Standalone Swagger UI (loads from CDN)