Swagger for Typescript-rest

Common errors

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

  cause 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]'

  cause 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

  cause 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]

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

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Adopt consistent and comprehensive JSDoc practices. Use `@param`, `@returns`, and general descriptions for classes and methods to enrich the generated documentation.

Install

• npm install typescript-rest-swagger npm
• yarn add typescript-rest-swagger yarn
• pnpm add typescript-rest-swagger pnpm

Imports

• swaggerGen
  wrong:

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

  correct:

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

  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
  wrong:

  import { Tags } from 'typescript-rest'

  correct:

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

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

  import { Response } from 'typescript-rest'

  correct:

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

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

  import { IsInt } from 'class-validator'

  correct:

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

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

Quickstart

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
    }
}