Jsdoc Open ApiTroubleshooting
Troubleshooting
Last updated:
Troubleshooting
Common issues and solutions when working with jsdoc-open-api.
CLI Not Found
Problem: jsdoc-open-api: command not found
Solutions:
- Use npx:
npx jsdoc-open-api generate src/- Install dependencies:
npm install commander cli-progress- Check optional dependencies installed:
npm list commander cli-progressNo Paths Generated
Problem: Generated spec has empty paths object
Causes:
- JSDoc comments missing
@openapitag:
// ❌ Won't be parsed
/**
* Get all users
*/
export function getUsers() {}
// ✅ Will be parsed
/**
* @openapi
* /users:
* get:
* summary: Get all users
*/
export function getUsers() {}- Wrong file paths in sources:
// Check your glob patterns
{
sources: [
"./src/routes/**/*.js", // Correct path?
];
}- Files not matching glob pattern:
# Test your glob patterns
npx glob "./src/routes/**/*.js"Invalid OpenAPI Specification
Problem: Generated spec fails validation
Solution: Validate required fields:
{
definition: {
openapi: "3.0.0", // Required
info: {
title: "My API", // Required
version: "1.0.0", // Required
},
},
}Webpack Plugin Not Working
Problem: Plugin doesn't generate spec in webpack build
Solutions:
- Verify webpack dependency:
npm install webpack- Check plugin configuration:
const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
const path = require("path");
new SwaggerCompilerPlugin(
path.join(__dirname, "public/swagger.json"), // Absolute path
[path.join(__dirname, "src/**/*.js")], // Absolute paths
{
/* definition */
},
{ verbose: true }, // Enable logging
);- Server-side only in Next.js:
webpack: (config, { isServer }) => {
if (!isServer) return config; // Skip on client
config.plugins.push(new SwaggerCompilerPlugin(/* ... */));
return config;
};TypeScript Errors
Problem: TypeScript type errors with imports
Solution: Install type definitions:
npm install --save-dev @types/swagger-jsdoc openapi-typesDuplicate Paths
Problem: Same path defined multiple times causes conflicts
Solution: Consolidate path definitions:
// ❌ Don't do this
/**
* @openapi
* /users:
* get:
* summary: Get users
*/
/**
* @openapi
* /users:
* post:
* summary: Create user
*/
// ✅ Do this
/**
* @openapi
* /users:
* get:
* summary: Get users
* post:
* summary: Create user
*/Schema References Not Working
Problem: $ref references not resolving
Cause: Schema not defined in components
Solution: Define schemas first:
/**
* @openapi
* components:
* schemas:
* User:
* type: object
* properties:
* id:
* type: integer
*/
/**
* @openapi
* /users:
* get:
* responses:
* 200:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/User'
*/Performance Issues
Problem: Generation is slow
Solutions:
- Limit source files:
{
sources: [
"./src/routes/**/*.js",
"!./src/**/*.test.js", // Exclude tests
"!./node_modules/**", // Exclude node_modules
];
}- Use specific paths:
// ❌ Slow
sources: ["./src/**/*.js"];
// ✅ Faster
sources: ["./src/routes/**/*.js", "./src/controllers/**/*.js"];- Cache results:
let cachedSpec = null;
async function getSpec() {
if (!cachedSpec) {
cachedSpec = await jsdocOpenApi({
/* options */
});
}
return cachedSpec;
}YAML Syntax Errors
Problem: YAML syntax errors in JSDoc comments
Common mistakes:
// ❌ Wrong indentation
/**
* @openapi
* /users:
* get:
* summary: Get users
*/
// ✅ Correct indentation (2 spaces)
/**
* @openapi
* /users:
* get:
* summary: Get users
*/
// ❌ Missing colon
/**
* @openapi
* /users
* get:
* summary: Get users
*/
// ✅ Colon after path
/**
* @openapi
* /users:
* get:
* summary: Get users
*/Debugging
Enable verbose logging:
# CLI
npx jsdoc-open-api generate -v src/
# Very verbose (debugging)
npx jsdoc-open-api generate -d src/Programmatic:
const spec = await jsdocOpenApi({
definition: {
/* ... */
},
sources: ["./src/**/*.js"],
verbose: true, // Enable logging
});Validation
Validate your generated spec:
# Using Swagger CLI
npm install -g @apidevtools/swagger-cli
swagger-cli validate swagger.json
# Using online validator
# Upload to https://editor.swagger.io/