routing-controllers-openapi-extra

A set of custom decorators and utilities for routing-controllers and routing-controllers-openapi. It simplifies file uploads, validation, and OpenAPI documentation generation in TypeScript/Node.js projects.

Installation

1npm install routing-controllers-openapi-extra

Important: Make sure to enable reflect-metadata and set experimentalDecorators and emitDecoratorMetadata to true in your tsconfig.json.

1{
2  "compilerOptions": {
3    "experimentalDecorators": true,
4    "emitDecoratorMetadata": true
5    // ...
6  }
7}

Features Overview

1. AsyncResolver

   • A helper class that collects and resolves Promises required for dynamic type definitions in decorators.

2. Validation & JSON Schema References

   • IsEntity(() => MyEntity, { each?: boolean }): Recursively validate nested objects or arrays of objects, dynamically resolved with class-transformer.
   • FixArrayJsonSchemaReference / FixItemJsonSchemaReference: Manually fix JSON schema references for arrays or single items.

3. OpenAPI Body Decorators

   • UseJsonBody: Automatically set up bodyParser.json() middleware and configure the OpenAPI request body schema.
   • UseUrlencodedBody: Use bodyParser.urlencoded(...) for form data.
   • UseMultipart: Set up multer for file uploads (any files), also annotates the request body in OpenAPI.

4. Request Guard & Resolver

   • RequestGuard: Custom request validation. Allows you to verify data before a controller method is called.
   • RequestResolver: Extract and optionally transform data into a DTO from request parameters, headers, etc.

5. File Upload Handling

   • UseMulter(MyDto): Centralized file upload processing. Automatically reads file-field definitions from your DTO class.
   • IsFile / IsFiles: Decorators to mark which DTO fields are single or multiple file uploads, with min/max size and MIME validation.
   • BodyMultipart: Merge req.body and req.files into a single object for easier processing.

6. OpenAPI Response Decorators

   • SuccessResponse(MyResponseDto, { isArray?: boolean }): Adds a documented 200 response.
   • Summary: Sets the summary in OpenAPI for a specific controller method.
   • responseError / responseSuccess: Utility functions to unify error and success responses.

Basic Example

1import { Expose } from "class-transformer";
2import {
3  Summary,
4  IsFiles,
5  SuccessResponse,
6  UseMulter,
7  BodyMultipart  
8} from "routing-controllers-openapi-extra";
9import { IsString } from "class-validator";
10import { Service } from "typedi";
11import { OpenAPI } from "routing-controllers-openapi";
12import FilesService from "./files.service";
13
14export class InputFilesDTO {
15  @IsFiles({
16    maxFiles: 5,
17    maxSize: "5MB",
18  })
19  @Expose()
20  files: Express.Multer.File[];
21
22  @Expose()
23  @IsString()
24  otherKey: string;
25}
26
27@Service()
28@OpenAPI({
29  tags: ["Files"],
30})
31@JsonController("/files")
32export class FilesController {
33  public constructor(private filesService: FilesService) {}
34
35  @Summary("Upload public files")
36  @SuccessResponse(UploadFileResponseDTO, { isArray: true })
37  @Post("/upload/public")
38  @UseMulter(InputFilesDTO)
39  public async uploadPublicFiles(@BodyMultipart() data: InputFilesDTO) {
40    return this.filesService.uploadFiles(data.files);
41  }
42}

License

MIT. See the LICENSE file for more details.