Introduction
Generate OpenAPI/Swagger specifications from JSDoc comments with support for multiple syntaxes, CLI, and build tool integration
Last updated:
@visulima/jsdoc-open-api
Automatically generate OpenAPI/Swagger specifications from JSDoc comments in your JavaScript/TypeScript code. Supports multiple syntax styles, provides a CLI tool, and integrates with build systems like Webpack and Next.js.
Key Features
Generation Methods
- CLI Tool - Command-line interface for quick generation
- Programmatic API - JavaScript/TypeScript API for build processes
- Webpack Plugin - Seamless integration with Webpack and Next.js
- Build Automation - Automatic regeneration during development
Syntax Support
- Standard OpenAPI - Full YAML/JSON syntax within JSDoc comments
- Short Syntax - Concise notation for common API definitions
- Flexible Comments - Multiple comment styles and formats
- Type Inference - Automatic type extraction from JSDoc tags
OpenAPI Features
- OpenAPI 3.0+ - Full OpenAPI 3.x specification support
- Paths & Operations - HTTP methods, parameters, responses
- Schemas & Models - Request/response body definitions
- Security - Authentication and authorization schemes
- Tags & Groups - Organize endpoints with tags
Performance
- Fast Parsing - Optimized comment extraction
- Incremental Generation - Only processes changed files
- Low Overhead - Minimal impact on build times
- Caching - Smart caching for repeated builds
Quick Start
import jsdocOpenApi from "@visulima/jsdoc-open-api";
const spec = await jsdocOpenApi({
definition: {
openapi: "3.0.0",
info: {
title: "My API",
version: "1.0.0",
},
},
sources: ["./src/routes/**/*.js"],
});
console.log(spec);Use Cases
API Documentation Generation
Automatically generate API documentation from your code:
/**
* @openapi
* /users:
* get:
* summary: Get all users
* tags: [Users]
* responses:
* 200:
* description: Success
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
export async function getUsers(req, res) {
const users = await db.users.findMany();
res.json(users);
}Generate specification:
npx jsdoc-open-api generate src/routes/Next.js Integration
Integrate with Next.js using the Webpack plugin:
// next.config.js
const withOpenApi = require("./with-open-api");
module.exports = withOpenApi({
definition: {
openapi: "3.0.0",
info: {
title: "Next.js API",
version: "1.0.0",
},
},
sources: ["./app/api/**/*.ts"],
output: "public/swagger.json",
})({
// Your Next.js config
});Build Process Integration
Integrate into your build pipeline:
// scripts/generate-api-docs.js
import jsdocOpenApi from "@visulima/jsdoc-open-api";
import { writeFileSync } from "fs";
async function generate() {
const spec = await jsdocOpenApi({
definition: {
openapi: "3.0.0",
info: {
title: "API Documentation",
version: process.env.npm_package_version,
},
servers: [
{
url: "https://api.example.com",
description: "Production",
},
],
},
sources: ["./src/api/**/*.ts"],
});
writeFileSync("./docs/api-spec.json", JSON.stringify(spec, null, 2));
console.log("API specification generated!");
}
generate();Add to package.json:
{
"scripts": {
"docs": "node scripts/generate-api-docs.js",
"prebuild": "npm run docs"
}
}Next Steps
Installation
Install and set up jsdoc-open-api
Quick Start
Generate your first OpenAPI spec
Syntax Guide
Learn the JSDoc comment syntax
API Reference
Complete API documentation
Browser and Server Support
This package is designed for build-time use:
- Node.js - Version 22.x and above
- Webpack - Version 5.x and above (for plugin usage)
- Environment - Build tools and development servers