{"id":12251,"library":"typescript-rest-swagger","title":"Swagger for Typescript-rest","description":"typescript-rest-swagger is a utility designed to generate OpenAPI (Swagger) specification files directly from projects built with the typescript-rest framework. It analyzes typescript-rest decorators, along with its own set of typescript-rest-swagger decorators (like @Tags, @Response, @Example), and JSDoc comments to construct comprehensive API documentation. The current stable version is 1.1.7, with recent releases focusing on bug fixes and dependency updates, indicating a maintenance-oriented release cadence. Its primary differentiator is its deep integration with typescript-rest, streamlining the documentation process for services developed using that specific REST framework by leveraging existing code annotations rather than requiring a separate definition language.","status":"active","version":"1.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/thiagobustamante/typescript-rest-swagger","tags":["javascript","typescript","typescript-rest","swagger","open api","rest","microservice","codegen","generation"],"install":[{"cmd":"npm install typescript-rest-swagger","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-rest-swagger","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-rest-swagger","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This tool integrates directly with projects built using `typescript-rest` to parse decorators and generate documentation.","package":"typescript-rest","optional":false},{"reason":"Required for decorator metadata; typically imported once at the application's entry point (e.g., `import 'reflect-metadata';`) in projects using TypeScript decorators.","package":"reflect-metadata","optional":false}],"imports":[{"note":"swaggerGen is a CLI tool, not an importable module. It's typically installed globally or executed via `npx` to ensure the correct version is run.","wrong":"import { swaggerGen } from 'typescript-rest-swagger'","symbol":"swaggerGen","correct":"npx swaggerGen -c ./swaggerConfig.json -p ./tsconfig.json"},{"note":"This decorator is provided by `typescript-rest-swagger` specifically for documenting API tags, distinct from `typescript-rest`'s core decorators.","wrong":"import { Tags } from 'typescript-rest'","symbol":"Tags","correct":"import { Tags } from 'typescript-rest-swagger'"},{"note":"The `@Response` decorator allows detailed documentation of HTTP responses (status codes, descriptions, examples) and is provided by `typescript-rest-swagger`.","wrong":"import { Response } from 'typescript-rest'","symbol":"Response","correct":"import { Response } from 'typescript-rest-swagger'"},{"note":"Decorators like `@IsInt`, `@IsLong`, `@IsFloat`, `@IsDouble` are specific to `typescript-rest-swagger` for OpenAPI type hints, not for runtime validation.","wrong":"import { IsInt } from 'class-validator'","symbol":"IsInt","correct":"import { IsInt } from 'typescript-rest-swagger'"}],"quickstart":{"code":"import { Path, GET, QueryParam } from 'typescript-rest';\nimport { Tags, Response } from 'typescript-rest-swagger';\n\ninterface Person { name: string; age: number; }\n\n/**\n * Service for managing people.\n * @hidden\n */\n@Path('people')\nexport class PeopleService {\n    /**\n     * Retrieves a list of people.\n     * @param minAge Optional: Filter by minimum age.\n     */\n    @GET\n    @Tags('UserManagement', 'ReadOperations')\n    @Response<Person[]>(200, 'Successfully retrieved people list')\n    @Response<{ message: string }>(400, 'Invalid input for minAge')\n    async getPeople(@QueryParam('minAge') minAge?: number): Promise<Person[]> {\n        return [{ name: 'Alice', age: 30 }]; // Example data\n    }\n}","lang":"typescript","description":"This quickstart demonstrates a simple `typescript-rest` service enhanced with `typescript-rest-swagger` decorators (`@Tags`, `@Response`) and JSDoc for OpenAPI documentation. To generate the `swagger.json` file: 1. Install `typescript-rest` and `reflect-metadata` in your project (`npm i typescript-rest reflect-metadata`). 2. Globally install `typescript-rest-swagger` (`npm i -g typescript-rest-swagger`). 3. Create a `swaggerConfig.json` (e.g., `{ \"swagger\": { \"outputDirectory\": \"./dist\", \"entryFile\": \"./src/services/MyService.ts\" } }`). 4. Ensure `tsconfig.json` has `\"experimentalDecorators\": true`, `\"emitDecoratorMetadata\": true`, and appropriate `\"lib\"` settings (e.g., `\"es2018\", \"dom\"`). 5. Run `swaggerGen -c ./swaggerConfig.json -p ./tsconfig.json`."},"warnings":[{"fix":"Prefer `npx swaggerGen` to ensure the project's locally installed version is used, or ensure global and local versions are aligned. For project-specific needs, consider adding it as a dev dependency and running via npm scripts.","message":"Installing 'typescript-rest-swagger' globally via `npm install -g` can lead to version mismatches or conflicts if your project's local dependency on `typescript-rest-swagger` or `typescript-rest` differs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check compatibility notes between 'typescript-rest-swagger' and 'typescript-rest' versions. Pin major versions of both packages in your project to avoid unexpected breaks.","message":"This tool relies heavily on the internal structure and decorators of 'typescript-rest'. Major version updates in 'typescript-rest' (e.g., from v2 to v3) might introduce breaking changes that prevent accurate Swagger generation until 'typescript-rest-swagger' is updated to support them.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `experimentalDecorators: true`, `emitDecoratorMetadata: true`, and appropriate `lib` entries (e.g., `es2018`, `dom`) are set. For custom module resolution, properly configure `baseUrl` and `paths` in `tsconfig.json` and pass it with the `-p` flag.","message":"Correct configuration of 'tsconfig.json' is crucial, especially for `experimentalDecorators`, `emitDecoratorMetadata`, `lib`, `baseUrl`, and `paths`. Missing or incorrect settings can lead to compilation errors or an inability to resolve project imports.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Adopt consistent and comprehensive JSDoc practices. Use `@param`, `@returns`, and general descriptions for classes and methods to enrich the generated documentation.","message":"The generated OpenAPI specification heavily depends on JSDoc comments on classes, methods, and parameters. Incomplete or malformed JSDoc might result in missing or inaccurate documentation in the final Swagger file.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install -g typescript-rest-swagger` to install it globally, or use `npx typescript-rest-swagger` to execute the local package without global installation.","cause":"The `swaggerGen` CLI tool was either not installed globally, or its installation directory is not in your system's PATH.","error":"'swaggerGen' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Install `typescript-rest` in your project: `npm install typescript-rest` (or `yarn add typescript-rest`). Also ensure `reflect-metadata` is installed and imported once at your application's entry point.","cause":"The project that `swaggerGen` is trying to analyze does not have `typescript-rest` installed as a dependency.","error":"Error: Cannot find module 'typescript-rest' from '[path]'"},{"fix":"Update `typescript-rest-swagger` to version 1.1.4 or newer: `npm install typescript-rest-swagger@latest`. If the issue persists, review your service types for potential complexities or circular dependencies.","cause":"An internal type resolution issue during the Swagger generation process. This was a common bug in earlier versions of the library.","error":"[TS-REST-SWAGGER] Error: Type error when generating swagger doc"},{"fix":"Verify the `entryFile` path in `swaggerConfig.json`. If using `tsconfig.json`, ensure its `compilerOptions.baseUrl` and `compilerOptions.paths` are correctly configured for your project's module resolution.","cause":"The `entryFile` path specified in `swaggerConfig.json` is incorrect, or the `tsconfig.json` (if used with `-p`) does not correctly resolve the path, especially with `baseUrl` or `paths` configurations.","error":"Error: [TS-REST-SWAGGER] Could not resolve entry file: [path]"}],"ecosystem":"npm"}