apidoc and swagger-jsdoc are both tools that generate interactive API documentation directly from source code comments in JavaScript projects. They enable developers to maintain up-to-date, human-readable API references without writing documentation separately from implementation. apidoc uses its own custom JSDoc-like comment syntax to describe endpoints, parameters, and responses, producing standalone HTML documentation. In contrast, swagger-jsdoc parses standard JSDoc comments enhanced with Swagger/OpenAPI annotations and integrates with the broader OpenAPI ecosystem, outputting machine-readable OpenAPI specification files (typically YAML or JSON) that can power tools like Swagger UI, Redoc, or automated client SDK generators.
apidoc vs swagger-jsdoc: Choosing the Right Tool for API Documentation
Both apidoc and swagger-jsdoc solve the same fundamental problem: keeping API documentation in sync with code by parsing specially formatted comments. But they diverge sharply in philosophy, output format, and ecosystem compatibility. Let’s break down what really matters when choosing between them.
Output Format: Standalone HTML vs OpenAPI Spec
apidoc generates a complete, self-contained HTML documentation site. You run the CLI, and it spits out a /doc folder full of static assets—no build pipeline or runtime server needed.
/**
* @api {get} /users Get all users
* @apiName GetUsers
* @apiGroup User
*
* @apiSuccess {Object[]} users List of user objects.
* @apiSuccess {String} users.name User name.
*/
app.get('/users', (req, res) => { /*...*/ });
Run apidoc -i src/ -o docs/, and you get browsable docs instantly. Great for quick internal reference—but that HTML is a dead end for automation.
swagger-jsdoc, by contrast, outputs a machine-readable OpenAPI 3.0 (or Swagger 2.0) specification—usually as JSON or YAML:
/**
* @openapi
* /users:
* get:
* summary: Get all users
* tags: [User]
* responses:
* 200:
* description: A list of users
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
app.get('/users', (req, res) => { /*...*/ });
This spec can feed into Swagger UI, Redoc, Postman, Stoplight, or even generate TypeScript clients via openapi-typescript. The trade-off? You need an extra step to visualize it.
Ecosystem Compatibility: Walled Garden vs Open Standard
apidoc lives in its own world. Its comment syntax is proprietary—useful for basic CRUD docs but incompatible with any tool outside its narrow scope. Want to import your API into Postman? Run contract tests with Dredd? Generate a React hook SDK? Not happening.
swagger-jsdoc embraces the OpenAPI Specification, the de facto industry standard. That means:
- Your comments become part of a portable, versionable contract.
- CI pipelines can validate request/response schemas against the spec.
- Gateways like Kong or AWS API Gateway can enforce policies based on it.
- Frontend devs can consume the spec to auto-generate typed API clients.
If your API crosses team or system boundaries, this interoperability isn’t just nice—it’s essential.
Developer Experience: Simplicity vs Precision
apidoc’s syntax is deliberately lightweight. You describe endpoints with @api, parameters with @apiParam, and responses with @apiSuccess. It’s easy to learn and sufficient for simple REST APIs.
But it lacks expressiveness for modern needs:
- No native support for request bodies beyond URL/query params.
- Can’t define reusable components (like shared error responses).
- Doesn’t model authentication schemes (OAuth2, API keys) in a structured way.
swagger-jsdoc leverages the full power of OpenAPI:
/**
* @openapi
* components:
* schemas:
* User:
* type: object
* properties:
* id: { type: integer }
* email: { type: string, format: email }
* securitySchemes:
* BearerAuth:
* type: http
* scheme: bearer
*/
You get strict typing, component reuse, security definitions, and even examples per status code. The cost? A steeper learning curve and more verbose comments.
Integration with Modern Toolchains
In a typical frontend/backend workflow:
- With
apidoc, your docs are a byproduct—useful for humans, invisible to machines. - With
swagger-jsdoc, your spec becomes a first-class artifact. You might even commit the generatedopenapi.jsonto Git and treat it as the source of truth.
For example, a frontend team can run:
npx openapi-typescript openapi.json -o src/api/types.ts
…and get fully typed fetch wrappers without ever reading the backend code.
When to Avoid Each
Avoid apidoc if:
- You’re building a public or partner-facing API.
- Your org uses API management platforms (Apigee, Azure API Management).
- You practice contract testing or need schema validation in CI.
Avoid swagger-jsdoc if:
- You’re documenting a tiny internal tool with no need for automation.
- Your team refuses to learn OpenAPI semantics.
- You need docs yesterday and can’t invest in spec hygiene.
The Bottom Line
Think of apidoc as a documentation printer: point it at code, get pretty pages. It’s fine for throwaway projects or legacy systems where OpenAPI would be overkill.
Think of swagger-jsdoc as an API contract engine: your comments become a living spec that drives testing, SDKs, and governance. It’s the right choice for serious APIs in professional environments.
If you’re starting a new project in 2024 and care about long-term maintainability, interoperability, and developer velocity across teams—go with swagger-jsdoc and the OpenAPI ecosystem. The initial overhead pays dividends fast.
- swagger-jsdoc:
Choose
swagger-jsdocif your project must adhere to the OpenAPI Specification (OAS) standard or integrate with the wider Swagger ecosystem—including Swagger UI, Postman, contract testing, or auto-generated SDKs. It’s ideal for public APIs, microservices architectures, or teams practicing design-first or contract-first development. Be prepared to manage OpenAPI schema complexity and validate your spec output. - apidoc:
Choose
apidocif you need a simple, self-contained documentation generator that produces ready-to-serve HTML without external dependencies. It’s well-suited for internal APIs or projects where you want zero-config, visually consistent docs with minimal setup. However, avoid it if you require OpenAPI compliance, automated client generation, or integration with API gateways and testing tools that expect standardized specs.
swagger-jsdoc
This library reads your JSDoc-annotated source code and generates an OpenAPI (Swagger) specification.
Getting started
Imagine having API files like these:
/**
* @openapi
* /:
* get:
* description: Welcome to swagger-jsdoc!
* responses:
* 200:
* description: Returns a mysterious string.
*/
app.get('/', (req, res) => {
res.send('Hello World!');
});
The library will take the contents of @openapi (or @swagger) with the following configuration:
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Hello World',
version: '1.0.0',
},
},
apis: ['./src/routes*.js'], // files containing annotations as above
};
const openapiSpecification = swaggerJsdoc(options);
The resulting openapiSpecification will be a swagger tools-compatible (and validated) specification.
System requirements
- Node.js 12.x or higher
You are viewing swagger-jsdoc v6 which is published in CommonJS module system.
Installation
npm install swagger-jsdoc --save
Or
yarn add swagger-jsdoc
Supported specifications
- OpenAPI 3.x
- Swagger 2
- AsyncAPI 2.0
Validation of swagger docs
By default swagger-jsdoc tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag failOnErrors to true. This is for instance useful if you want to verify that your swagger docs validate using a unit test.
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false.
definition: {
openapi: '3.0.0',
info: {
title: 'Hello World',
version: '1.0.0',
},
},
apis: ['./src/routes*.js'],
};
const openapiSpecification = swaggerJsdoc(options);
Documentation
Click on the version you are using for further details: