swagger-autogen

Statically analyzes Express.js route definitions to automatically extract HTTP endpoints, methods (GET, POST, PUT, DELETE, PATCH), and path parameters without requiring manual annotation. Uses AST parsing or regex-based pattern matching on route handler files to identify route() calls and method chains, then maps these to OpenAPI path objects with operationId generation.

Automatically identifies middleware functions applied to routes and route groups, capturing middleware chains and their execution order. Analyzes middleware stack by inspecting app.use() calls and route-level middleware parameters, then documents which endpoints are protected or modified by specific middleware (authentication, validation, logging, etc.).

Automatically identifies HTTP response status codes (200, 201, 400, 401, 404, 500, etc.) returned by endpoints by analyzing route handlers and response patterns. Uses code pattern matching to detect res.status().json(), res.send(), and error handling blocks, mapping these to OpenAPI response objects with appropriate status codes and descriptions.

Automatically identifies request parameters (path params, query strings, request body) from Express route definitions and handler signatures. Analyzes route patterns (e.g., /users/:id) to extract path parameters, inspects req.query and req.body usage in handlers, and maps these to OpenAPI parameter objects with types and descriptions where detectable.

Generates complete OpenAPI 2.0 (Swagger) or OpenAPI 3.0 specification documents from extracted endpoint metadata, combining discovered routes, methods, parameters, responses, and middleware into a valid JSON or YAML spec file. Supports customization through configuration objects to set API title, version, base path, and security schemes, then writes output to a swagger.json or openapi.json file.

Integrates with TypeScript type annotations and JSDoc comments to enhance parameter and response schema inference. Reads TypeScript interfaces, type definitions, and JSDoc @param/@returns annotations from route handler files to automatically populate request/response schemas in the generated OpenAPI spec, improving schema accuracy beyond plain JavaScript detection.

Provides integration with Swagger UI to serve interactive API documentation directly from the Express application. Generates or references the swagger.json spec and configures Swagger UI middleware to expose an interactive endpoint (typically /api-docs or /swagger) where developers can explore endpoints, test requests, and view documentation in a browser-based interface.

Allows developers to customize the generated OpenAPI specification through a configuration object passed to swagger-autogen, enabling control over API metadata (title, version, description, base path), security schemes, servers, tags, and other top-level spec properties without modifying generated code. Configuration is typically defined in a separate config file or inline in the generation script.

Supports regenerating the OpenAPI specification when route files change, allowing developers to re-run swagger-autogen to update the spec with newly discovered endpoints, modified parameters, or changed response codes. Can be integrated into development workflows or CI/CD pipelines to keep specs in sync with code changes automatically.

Analyzes multiple Express route files and aggregates discovered endpoints into a single OpenAPI specification. Supports modular route organization where routes are split across multiple files (e.g., routes/users.js, routes/products.js) and combines them into a unified spec, maintaining route grouping and tags for logical organization.