Jsdoc Open ApiQuick Start
Quick Start
Last updated:
Quick Start
Generate your first OpenAPI specification from JSDoc comments in under 5 minutes.
Add JSDoc Comments
Add OpenAPI documentation to your API endpoints:
// src/routes/users.js
/**
* @openapi
* /users:
* get:
* summary: Get all users
* description: Retrieve a list of all users
* tags:
* - Users
* responses:
* 200:
* description: List of users
* 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);
}
/**
* @openapi
* /users/{id}:
* get:
* summary: Get user by ID
* tags:
* - Users
* parameters:
* - name: id
* in: path
* required: true
* schema:
* type: integer
* responses:
* 200:
* description: User found
* 404:
* description: User not found
*/
export async function getUserById(req, res) {
const user = await db.users.findUnique({ where: { id: req.params.id } });
if (!user) {
return res.status(404).json({ error: "User not found" });
}
res.json(user);
}Generate with CLI
Use the CLI to generate the specification:
# Initialize configuration
npx jsdoc-open-api init
# Generate specification
npx jsdoc-open-api generate src/routes/Output swaggerSpec.json:
{
"openapi": "3.0.0",
"info": {
"title": "My API",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
"summary": "Get all users",
"description": "Retrieve a list of all users",
"tags": ["Users"],
"responses": {
"200": {
"description": "List of users"
}
}
}
},
"/users/{id}": {
"get": {
"summary": "Get user by ID",
"tags": ["Users"],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": { "description": "User found" },
"404": { "description": "User not found" }
}
}
}
}
}Generate Programmatically
Use the JavaScript API:
// scripts/generate-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: "My API",
version: "1.0.0",
description: "API documentation",
},
servers: [
{
url: "http://localhost:3000",
description: "Development server",
},
],
},
sources: ["./src/routes/**/*.js"],
});
writeFileSync("./swagger.json", JSON.stringify(spec, null, 2));
console.log("✅ OpenAPI spec generated!");
}
generate();Run it:
node scripts/generate-docs.jsShort Syntax
Use the concise short syntax:
/**
* GET /api/posts
* @summary Get all posts
* @tags Posts
* @response 200 - Success
*/
export async function getPosts(req, res) {
// ...
}
/**
* POST /api/posts
* @summary Create post
* @tags Posts
* @bodyparam {string} title.required - Post title
* @bodyparam {string} content - Post content
* @response 201 - Created
* @response 400 - Validation error
*/
export async function createPost(req, res) {
// ...
}Define Schemas
Add reusable schemas:
/**
* @openapi
* components:
* schemas:
* User:
* type: object
* required:
* - id
* - email
* properties:
* id:
* type: integer
* email:
* type: string
* format: email
* name:
* type: string
* createdAt:
* type: string
* format: date-time
*/Reference schemas in endpoints:
/**
* @openapi
* /users:
* post:
* requestBody:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/User'
* responses:
* 201:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/User'
*/
export async function createUser(req, res) {
// ...
}View Documentation
Use Swagger UI to view your specification:
// server.js with Express
import express from "express";
import swaggerUi from "swagger-ui-express";
import spec from "./swagger.json" assert { type: "json" };
const app = express();
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));
app.listen(3000, () => {
console.log("API docs: http://localhost:3000/api-docs");
});Next Steps
Syntax Guide
Learn all JSDoc comment syntaxes
CLI Usage
Explore CLI commands and options
Webpack Integration
Integrate with build tools