CLI Plugin

Hệ thống reflection metadata của TypeScript có một số hạn chế khiến việc xác định một class gồm những property nào, hoặc nhận biết một property là optional hay required, trở nên không thể thực hiện được. Tuy nhiên, một số hạn chế này có thể được giải quyết tại thời điểm compile. Nest cung cấp một plugin giúp tăng cường quá trình compile TypeScript để giảm lượng code khung (boilerplate) cần viết.

Overview (tổng quan)

Swagger plugin sẽ tự động:

• gắn @ApiProperty cho tất cả property của DTO trừ khi dùng @ApiHideProperty
• đặt property required dựa trên dấu hỏi (question mark) (ví dụ: name?: string sẽ đặt required: false)
• đặt property type hoặc enum dựa trên type (hỗ trợ cả array)
• đặt property default dựa trên giá trị mặc định đã gán
• đặt một số rule validation dựa trên decorator của class-validator (nếu classValidatorShim được đặt là true)
• thêm response decorator cho mọi endpoint với status và type (response model) phù hợp
• sinh mô tả (description) cho property và endpoint dựa trên comment (nếu introspectComments được đặt là true)
• sinh giá trị ví dụ (example) cho property dựa trên comment (nếu introspectComments được đặt là true)

Lưu ý rằng tên file của bạn phải có một trong các hậu tố sau: ['.dto.ts', '.entity.ts'] (ví dụ: create-user.dto.ts) để được plugin phân tích.

Nếu bạn dùng hậu tố khác, bạn có thể điều chỉnh hành vi của plugin bằng option dtoFileNameSuffix (xem bên dưới).

Trước đây, nếu muốn có trải nghiệm tương tác với Swagger UI, bạn phải lặp lại rất nhiều code để cho package biết model/component của bạn nên được khai báo trong spec như thế nào. Ví dụ, bạn có thể định nghĩa một class CreateUserDto đơn giản như sau:

export class CreateUserDto {
  @ApiProperty()
  email: string;

  @ApiProperty()
  password: string;

  @ApiProperty({ enum: RoleEnum, default: [], isArray: true })
  roles: RoleEnum[] = [];

  @ApiProperty({ required: false, default: true })
  isEnabled?: boolean = true;
}

Với các project quy mô vừa, đây chưa phải vấn đề lớn, nhưng nó sẽ trở nên dài dòng và khó duy trì khi bạn có một số lượng lớn class.

Bằng cách bật Swagger plugin, class định nghĩa ở trên có thể được viết đơn giản như sau:

export class CreateUserDto {
  email: string;
  password: string;
  roles: RoleEnum[] = [];
  isEnabled?: boolean = true;
}

Do đó, nếu bạn muốn dựa vào annotation tự động để sinh tài liệu và vẫn muốn có validation ở runtime, thì decorator của class-validator vẫn là bắt buộc.

Plugin sẽ tự thêm các decorator phù hợp dựa trên Abstract Syntax Tree (cây cú pháp trừu tượng). Vì vậy bạn không cần phải vật lộn với các decorator @ApiProperty rải khắp code.

Comments introspection (phân tích comment)

Khi bật tính năng phân tích comment (comments introspection), CLI plugin sẽ sinh description và example value cho property dựa trên comment.

Ví dụ, với property roles sau:

/**
 * A list of user's roles
 * @example ['admin']
 */
@ApiProperty({
  description: `A list of user's roles`,
  example: ['admin'],
})
roles: RoleEnum[] = [];

Bạn phải viết lặp lại cả description và example. Khi bật introspectComments, CLI plugin có thể trích xuất các comment này và tự động cung cấp description (và example, nếu có) cho property. Bây giờ, property trên có thể được khai báo đơn giản như sau:

/**
 * A list of user's roles
 * @example ['admin']
 */
roles: RoleEnum[] = [];

Có hai option plugin là dtoKeyOfComment và controllerKeyOfComment dùng để tùy biến cách plugin gán giá trị cho decorator ApiProperty và ApiOperation. Xem ví dụ dưới đây:

export class SomeController {
  /**
   * Create some resource
   */
  @Post()
  create() {}
}

Điều này tương đương với chỉ thị sau:

@ApiOperation({ summary: "Create some resource" })

Với controller, bạn không chỉ cung cấp được summary mà còn có thể cung cấp description (remarks), tag (như @deprecated), và response example, như sau:

/**
 * Create a new cat
 *
 * @remarks This operation allows you to create a new cat.
 *
 * @deprecated
 * @throws {500} Something went wrong.
 * @throws {400} Bad Request.
 */
@Post()
async create(): Promise<Cat> {}

Từ @nestjs/swagger v12, tag @param cũng được nhận diện, nhờ đó description của route parameter có thể lấy từ cùng một doc comment:

/**
 * List cats
 *
 * @param breed Filter results by breed
 * @param limit Maximum number of results to return
 */
@Get()
findAll(@Query('breed') breed?: string, @Query('limit') limit?: number) {}

Plugin sẽ thêm description vào @ApiQuery() mà nó đã tự sinh cho các tham số @Query() optional, sinh @ApiQuery({ name, description }) cho các query parameter bắt buộc đã được viết doc comment, và sinh @ApiParam({ name, description }) cho các tham số @Param() đã được viết doc comment.

Description được khớp theo tên biến (variable name), đây cũng chính là thứ mà @param mô tả — vì vậy @Query('order_by') orderBy: string sẽ được tài liệu hóa dưới dạng @param orderBy ..., không phải @param order_by .... Các decorator @ApiQuery() / @ApiParam() khai báo rõ ràng luôn được ưu tiên hơn và không bao giờ bị ghi đè.

Using the CLI plugin (dùng CLI plugin)

Để bật plugin, mở nest-cli.json (nếu bạn dùng Nest CLI) và thêm cấu hình plugins sau:

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

Bạn có thể dùng property options để tùy biến hành vi của plugin.

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": false,
          "introspectComments": true,
          "skipAutoHttpCode": true
        }
      }
    ]
  }
}

Property options phải tuân theo interface sau:

export interface PluginOptions {
  dtoFileNameSuffix?: string[];
  controllerFileNameSuffix?: string[];
  classValidatorShim?: boolean;
  dtoKeyOfComment?: string;
  controllerKeyOfComment?: string;
  introspectComments?: boolean;
  skipAutoHttpCode?: boolean;
  esmCompatible?: boolean;
}

Nhớ xóa thư mục /dist và rebuild lại ứng dụng mỗi khi cập nhật option của plugin. Nếu bạn không dùng CLI mà thay vào đó dùng cấu hình webpack tùy chỉnh, bạn có thể dùng plugin này kết hợp với ts-loader:

getCustomTransformers: (program: any) => ({
  before: [require('@nestjs/swagger/plugin').before({}, program)]
}),

SWC builder

Với các setup thông thường (không phải monorepo), để dùng CLI Plugin với SWC builder, bạn cần bật type checking, như mô tả ở đây.

$ nest start -b swc --type-check

Với setup monorepo, làm theo hướng dẫn ở đây.

$ npx ts-node src/generate-metadata.ts
# hoặc npx ts-node apps/{YOUR_APP}/src/generate-metadata.ts

Bây giờ, file metadata đã serialize phải được load bằng method SwaggerModule#loadPluginMetadata, như bên dưới:

import metadata from './metadata.js'; // <-- file được tự sinh bởi "PluginMetadataGenerator"

await SwaggerModule.loadPluginMetadata(metadata); // <-- ở đây
const document = SwaggerModule.createDocument(app, config);

Integration with ts-jest (e2e tests) — tích hợp với ts-jest (test e2e)

Để chạy e2e test, ts-jest compile source code của bạn ngay tại thời điểm chạy (on the fly), trong memory. Điều này có nghĩa là nó không dùng Nest CLI compiler và không áp dụng bất kỳ plugin hay AST transformation nào.

Để bật plugin, tạo file sau trong thư mục e2e test của bạn:

const transformer = require('@nestjs/swagger/plugin');

module.exports.name = 'nestjs-swagger-transformer';
// bạn nên đổi số version này mỗi khi thay đổi cấu hình bên dưới - nếu không jest sẽ không phát hiện được thay đổi
module.exports.version = 1;

module.exports.factory = (cs) => {
  return transformer.before(
    {
      // options của @nestjs/swagger/plugin (có thể để trống)
    },
    cs.program, // "cs.tsCompiler.program" cho các phiên bản Jest cũ hơn (<= v27)
  );
};

Sau khi thiết lập xong, import AST transformer trong file cấu hình jest của bạn. Theo mặc định (trong ứng dụng starter), file cấu hình e2e test nằm trong thư mục test và tên là jest-e2e.json.

Nếu bạn dùng jest@<29, hãy dùng đoạn code dưới đây.

{
  ... // các cấu hình khác
  "globals": {
    "ts-jest": {
      "astTransformers": {
        "before": ["<đường dẫn đến file đã tạo ở trên>"]
      }
    }
  }
}

Nếu bạn dùng jest@^29, hãy dùng đoạn code dưới đây, vì cách làm trước đó đã bị deprecated.

{
  ... // các cấu hình khác
  "transform": {
    "^.+\\.(t|j)s$": [
      "ts-jest",
      {
        "astTransformers": {
          "before": ["<đường dẫn đến file đã tạo ở trên>"]
        }
      }
    ]
  }
}

Troubleshooting jest (e2e tests) — xử lý sự cố jest (test e2e)

Trong trường hợp jest không nhận ra các thay đổi cấu hình của bạn, có thể do Jest đã cache kết quả build trước đó. Để áp dụng cấu hình mới, bạn cần xóa thư mục cache của Jest.

Để xóa thư mục cache, chạy lệnh sau trong thư mục project NestJS của bạn:

$ npx jest --clearCache

Trong trường hợp việc xóa cache tự động không thành công, bạn vẫn có thể xóa thư mục cache bằng tay với các lệnh sau:

# Tìm thư mục cache của jest (thường là /tmp/jest_rs)
# bằng cách chạy lệnh sau trong thư mục gốc project NestJS
$ npx jest --showConfig | grep cache
# ví dụ kết quả:
#   "cache": true,
#   "cacheDirectory": "/tmp/jest_rs"

# Xóa hoặc làm trống thư mục cache của Jest
$ rm -rf  <giá trị cacheDirectory>
# ví dụ:
# rm -rf /tmp/jest_rs