Registry / web-framework / typescript-rest-swagger

typescript-rest-swagger

library1.1.7jsnpmunverified

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.

web-framework serialization

npm install typescript-rest-swagger

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-REST-SW

typescript-rest-swagger

web-frameworkjavascriptv1.1.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

swaggerGen

✓ npx swaggerGen -c ./swaggerConfig.json -p ./tsconfig.json

✗ import { swaggerGen } from 'typescript-rest-swagger'

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.

Tags

✓ import { Tags } from 'typescript-rest-swagger'

✗ import { Tags } from 'typescript-rest'

This decorator is provided by `typescript-rest-swagger` specifically for documenting API tags, distinct from `typescript-rest`'s core decorators.

Response

✓ import { Response } from 'typescript-rest-swagger'

✗ import { Response } from 'typescript-rest'

The `@Response` decorator allows detailed documentation of HTTP responses (status codes, descriptions, examples) and is provided by `typescript-rest-swagger`.

IsInt

✓ import { IsInt } from 'typescript-rest-swagger'

✗ import { IsInt } from 'class-validator'

Decorators like `@IsInt`, `@IsLong`, `@IsFloat`, `@IsDouble` are specific to `typescript-rest-swagger` for OpenAPI type hints, not for runtime validation.

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`.

import { Path, GET, QueryParam } from 'typescript-rest'; import { Tags, Response } from 'typescript-rest-swagger'; interface Person { name: string; age: number; } /** * Service for managing people. * @hidden */ @Path('people') export class PeopleService { /** * Retrieves a list of people. * @param minAge Optional: Filter by minimum age. */ @GET @Tags('UserManagement', 'ReadOperations') @Response<Person[]>(200, 'Successfully retrieved people list') @Response<{ message: string }>(400, 'Invalid input for minAge') async getPeople(@QueryParam('minAge') minAge?: number): Promise<Person[]> { return [{ name: 'Alice', age: 30 }]; // Example data } }

Debug

Known issues

gotchaInstalling '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.

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.

affects: >=1.0.0

breakingThis 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.

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.

affects: >=1.0.0

gotchaCorrect 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.

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.

affects: >=1.0.0

gotchaThe 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.

fix

Adopt consistent and comprehensive JSDoc practices. Use `@param`, `@returns`, and general descriptions for classes and methods to enrich the generated documentation.

affects: >=1.0.0

Errors

Common errors & fixes

'swaggerGen' is not recognized as an internal or external command, operable program or batch file.

The `swaggerGen` CLI tool was either not installed globally, or its installation directory is not in your system's PATH.

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.

Error: Cannot find module 'typescript-rest' from '[path]'

The project that `swaggerGen` is trying to analyze does not have `typescript-rest` installed as a dependency.

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.

[TS-REST-SWAGGER] Error: Type error when generating swagger doc

An internal type resolution issue during the Swagger generation process. This was a common bug in earlier versions of the library.

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.

Error: [TS-REST-SWAGGER] Could not resolve entry file: [path]

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.

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.

Upgrade

Version history

1.1.7latest on npm

Audit

Dependencies

typescript-restrequiredThis tool integrates directly with projects built using `typescript-rest` to parse decorators and generate documentation.

reflect-metadatarequiredRequired for decorator metadata; typically imported once at the application's entry point (e.g., `import 'reflect-metadata';`) in projects using TypeScript decorators.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/thiagobustamante/typescript-rest-swagger ↗

packagehttps://www.npmjs.com/package/typescript-rest-swagger ↗