swagger-autogen

swagger-autogen is a Node.js dev-time tool that builds a Swagger/OpenAPI specification JSON file by parsing your Express (or Express-like) route files directly, rather than requiring you to hand-write JSDoc-style Swagger annotations above every endpoint. It uses the acorn JavaScript parser to walk the AST of your route and middleware files, identifying HTTP methods (get, post, put, delete, etc.), paths, path/query/header/body parameters, and middleware chains, then assembles that into a valid specification document.

Because the heavy lifting is static analysis rather than manual annotation, teams keep their existing route code as the single source of truth: the spec regenerates automatically as routes change, instead of drifting out of sync with hand-maintained comments. Optional inline comments let you enrich the generated output with descriptions, response schemas, and security definitions where the automatic inference isn’t enough. It supports both OpenAPI 3 and Swagger 2 output formats and multiple response languages.

It’s typically wired into a small standalone script (e.g. swagger.js) that’s run via Node once during development or as part of a build/CI step, producing a swagger-output.json file that’s then served (commonly through swagger-ui-express) rather than imported and called from application request-handling code at runtime.

What You Get

• Automatic detection of HTTP methods, paths, and route parameters directly from your route files
• Support for both OpenAPI 3 and Swagger 2 output formats
• Optional inline comments to enrich auto-detected routes with descriptions, schemas, and security definitions
• Automatic inference of headers, query parameters, request bodies, and response status codes
• Multi-language support for generated response descriptions
• A single generated JSON spec file ready to serve with swagger-ui-express or similar tooling

Common Use Cases

• Generating an OpenAPI spec for an existing Express API that has no prior Swagger documentation
• Keeping API docs in sync with route changes without maintaining separate annotation comments
• Running spec generation as a pre-build or CI step so the served documentation always reflects current routes
• Bootstrapping a swagger-ui-express endpoint quickly for internal or partner-facing API docs
• Migrating a codebase from manually written Swagger comments to a generated, route-driven spec

Under The Hood

Architecture The package is a single callable export (swagger-autogen.js) that configures a shared options object and delegates to modules under src/: handle-files.js resolves and reads the target route files, code-parser.js walks each file’s AST (built via the acorn parser) to extract variable declarations and route-registration call expressions, and handle-data.js (the largest module) converts those parsed constructs into Swagger/OpenAPI path, parameter, and response objects, consulting swagger-tags.js for language-specific tag text and tables.js/statics.js for lookup constants. The flow is a straightforward pipeline (read files -> parse AST -> extract route metadata -> assemble spec -> merge with deepmerge -> write JSON via fs) with no dependency injection or plugin architecture; a change to the core AST-to-route-metadata mapping in code-parser.js or handle-data.js would ripple through the entire generation output.

Tech Stack It’s a plain CommonJS Node.js module with a small dependency footprint: acorn for JavaScript AST parsing, deepmerge for combining generated spec fragments with user-supplied data, glob for resolving file patterns in the endpointsFiles argument, and json5 for lenient JSON parsing of user config. There’s no web framework, database, or build step of its own — it’s a source-analysis library consumed by whichever Express-like app it’s pointed at, with a companion static docs site under website/ built separately (Docusaurus-style docs/ folder structure).

Code Quality Tests live under test/ and use tape/tape-promise for unit assertions against src/utils.js and src/handle-data.js (unit.test.utils.js, unit.test.handle-data.js), run via npm test, with eslint --ignore-path .gitignore . as a pretest step using eslint:recommended. Coverage is narrow relative to the codebase size — the parsing-heavy modules (code-parser.js, handle-files.js) that carry most of the complexity have no dedicated test files. Error handling favors defensive try/catch blocks that fall back to returning the original input on parse failure rather than throwing, which keeps the tool from crashing on malformed input but can mask parsing bugs silently. Naming and structure are consistent and functions carry JSDoc comments, though there’s no TypeScript (only a hand-written .d.ts for the public API) and no CI configuration was found in the repo.

What Makes It Unique Unlike comment-annotation-based Swagger generators that require developers to hand-write JSDoc blocks above each route, swagger-autogen’s core idea is deriving the spec from static analysis of the route code itself — parsing the actual app.get(...), app.post(...), and middleware use(...) call expressions via an AST rather than regex or comment scraping. This lets a spec exist for a codebase with zero annotations, with inline comments treated as optional enrichment rather than the primary data source — a meaningfully different default than most tools in this space, though the underlying parsing patterns and heuristics themselves are standard AST-walking rather than a novel algorithmic approach.