Tiếp tục với series, sau Bài 22 TaskFlow API đã có khá nhiều route. Bài này mình sẽ giới thiệu với mọi người về tài liệu API với Swagger trong NestJS, để người dùng API biết gửi gì, nhận gì mà không phải đọc code.
1. Swagger và OpenAPI.
OpenAPI là định dạng chuẩn (JSON/YAML) mô tả một REST API: các route, tham số, body, response và cách xác thực. Swagger UI đọc file đó và hiển thị thành trang web có nút "Try it out" để gọi thử API.
Package @nestjs/swagger (12.1.2) đọc controller, DTO và decorator trong code để sinh ra tài liệu OpenAPI, nên tài liệu luôn khớp với code:
npm install @nestjs/swagger
2. Tạo trang /docs với DocumentBuilder.
- src/main.ts (đoạn trích, thêm import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';)
const config = app.get<ConfigType<typeof appConfig>>(appConfig.KEY);
app.useGlobalInterceptors(new TimeoutInterceptor(config.requestTimeout));
if (config.docsEnabled) {
const docConfig = new DocumentBuilder()
.setTitle('TaskFlow API')
.setDescription('REST API quản lý project và task của TaskFlow')
.setVersion('1.0')
.addBearerAuth() // nút Authorize nhận access token JWT
.build();
// Chỉ tạo tài liệu khi có người mở /docs lần đầu
SwaggerModule.setup('docs', app, () =>
SwaggerModule.createDocument(app, docConfig),
);
}
await app.listen(config.port);
Trong đó:
DocumentBuildertạo phần thông tin chung: tên, mô tả, phiên bản.addBearerAuth()khai báo kiểu xác thựcAuthorization: Bearercủa Bài 20.SwaggerModule.createDocument()quét mọi route để sinh tài liệu. Truyền nó dưới dạng hàm thì tài liệu chỉ được tạo khi cần, và lúc đó versioning đã bật nên path có đủ/api/v1.setup('docs', ...)mở Swagger UI ở/docs, file JSON ở/docs-jsonvà YAML ở/docs-yaml. Các path này không có global prefixapi.
docsEnabled là process.env.NODE_ENV !== 'production' trong src/config/app.config.ts; envSchema (Bài 14) thêm NODE_ENV: z.enum(['development', 'production', 'test']).default('development') và .env.example thêm NODE_ENV=development.
Chú ý: Route của Swagger không đi qua guard của NestJS nên /docs ai cũng mở được, kể cả khi chưa đăng nhập. Tài liệu cho người lạ biết toàn bộ route của API, vì vậy mình chỉ bật ở local; khi deploy nhớ đặt NODE_ENV=production, vì mặc định là development nên quên biến này là /docs bật trên server (Bài 25 sẽ đổi thành chỉ bật khi NODE_ENV=development). Nếu cần tài liệu trên server, hãy đặt nó sau một lớp xác thực riêng (VD Basic Auth ở reverse proxy).
3. Tài liệu tự sinh từ DTO với CLI plugin.
Mở /docs-json lúc này sẽ thấy đủ route nhưng DTO rỗng, query DTO cũng không có tham số nào:
curl http://localhost:3000/docs-json
# ..."CreateProjectDto":{"type":"object","properties":{}}...
TypeScript không lưu danh sách property của class lúc chạy, nên Swagger chỉ thấy property có gắn @ApiProperty(), VD @ApiProperty({ example: 'Website toidicode.com', maxLength: 100 }) name: string;. Gắn tay cho mọi DTO vừa dài vừa dễ lệch với validation, nên NestJS có CLI plugin tự thêm các decorator đó lúc build:
- nest-cli.json
{
"$schema": "https://json.schemastore.org/nest-cli",
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"deleteOutDir": true,
"plugins": [
{
"name": "@nestjs/swagger",
"options": { "introspectComments": true }
}
]
}
}
Trong đó:
- Plugin chỉ đọc file đuôi
.dto.ts/.entity.ts(DTO) và.controller.ts, chỉ chạy khi build bằng Nest CLI (npm run start,nest build). - Property có
?là không bắt buộc; kiểu, enum, mảng và giá trị mặc định lấy từ TypeScript; validator như@MaxLength(100),@IsEmail()thànhmaxLength,format: email. Validation vẫn doclass-validatorlàm. introspectComments: truelấy comment/** */làm mô tả, thẻ@examplelàm giá trị mẫu.
Các DTO dùng mapped types (Bài 7) đổi import PartialType, PickType từ @nestjs/mapped-types sang @nestjs/swagger, nếu không UpdateProjectDto sẽ rỗng. Thêm comment cho DTO:
- src/tasks/dto/create-task.dto.ts (đoạn trích)
/**
* Tiêu đề task
* @example "Viết bài Swagger"
*/
@IsString()
@IsNotEmpty()
@MaxLength(200)
title: string;
Giá trị mẫu là chuỗi có dấu cách thì phải đặt trong dấu ", nếu không plugin bỏ qua. Comment trên route handler thành dòng tóm tắt (summary) của route, thẻ @param thành mô tả cho query/param.
Plugin cũng có lúc đoán sai: page: number = 1 không có ? nên bị đánh dấu bắt buộc. Khi đó gắn decorator để ghi đè, plugin chỉ điền phần còn thiếu:
- src/common/pagination/pagination-query.dto.ts (đoạn trích, thêm import { ApiPropertyOptional } from '@nestjs/swagger';)
@ApiPropertyOptional() // có giá trị mặc định nên không bắt buộc
@Type(() => Number)
@IsInt()
@Min(1)
@Max(1000) // Trang quá sâu thì dùng cursor (offset lớn chạy chậm)
page: number = 1;
limit làm tương tự; sort của ListProjectsQueryDto có kiểu keyof nên dùng @ApiPropertyOptional({ type: String }).
4. @ApiTags và @ApiBearerAuth.
Mặc định route được nhóm theo tên controller. @ApiTags() đặt tên nhóm, @ApiBearerAuth() đánh dấu route cần access token:
- src/projects/projects.controller.ts (đoạn trích, thêm import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';)
@ApiTags('Projects')
@ApiBearerAuth() // mọi route cần access token
@Controller('projects')
export class ProjectsController {
constructor(private readonly projectsService: ProjectsService) {}
/**
* Danh sách project của user đang đăng nhập
*/
@Get()
findAll(
TasksController, ActivitiesController, AttachmentsController gắn tương tự. AuthController chỉ gắn @ApiTags('Auth'), còn @ApiBearerAuth() đặt riêng trên me() vì register, login là @Public(). Param id của activity là ObjectId (Bài 19), thêm @ApiParam({ name: 'id', type: String }) để không hiện thành object.
Trên /docs, các bạn gọi POST /api/v1/auth/login bằng "Try it out", copy accessToken, bấm Authorize và dán token (không cần chữ Bearer). Từ đó các route có biểu tượng ổ khoá sẽ tự gửi header Authorization.
5. Tài liệu cho route upload file.
Swagger không biết FilesInterceptor nhận file gì, nên cần một class mô tả body multipart/form-data:
- src/attachments/dto/upload-attachments.dto.ts
import { ApiProperty } from '@nestjs/swagger';
// Chỉ dùng cho tài liệu: file do FilesInterceptor nhận, không qua ValidationPipe
export class UploadAttachmentsDto {
@ApiProperty({
type: 'array',
items: { type: 'string', format: 'binary' },
maxItems: 5,
description: 'PNG, JPEG, WebP hoặc PDF, tối đa 5 MB mỗi file',
})
files: Express.Multer.File[];
}
Rồi gắn lên route upload của AttachmentsController, ngay dưới @Post():
@ApiConsumes('multipart/form-data')
@ApiBody({ type: UploadAttachmentsDto })
Swagger UI sẽ hiện nút chọn file cho field files. Route tải file thêm @ApiProduces('application/octet-stream') và @ApiOkResponse({ description: 'Nội dung file', schema: { type: 'string', format: 'binary' } }).
6. Kiểm tra tài liệu.
Khởi động lại bằng npm run start (đổi option của plugin thì xoá dist rồi build lại):
curl http://localhost:3000/docs-json
# ..."/api/v1/auth/me":{"get":{...,"security":[{"bearer":[]}],"summary":"Thông tin user đang đăng nhập","tags":["Auth"]}}...
# ..."CreateProjectDto":{"type":"object","properties":{"name":{"type":"string","description":"Tên project",
# "example":"Website toidicode.com","maxLength":100},"description":{"type":"string","maxLength":500}},"required":["name"]}...
NODE_ENV=production npm run start
curl http://localhost:3000/docs
# 404 (Cannot GET /docs)
Plugin cũng thêm status code (201 cho POST, 204 theo @HttpCode) nhưng chỉ mô tả được response khi kiểu trả về là class. TaskFlow trả về kiểu của Prisma và bọc trong { data } nên phần response còn sơ sài; khi cần, các bạn dùng @ApiOkResponse({ type: ... }) với một class mô tả response.
7. Lời kết.
Như vậy mình đã giới thiệu với mọi người về tài liệu API với Swagger trong NestJS: DocumentBuilder, SwaggerModule, CLI plugin sinh tài liệu từ DTO, @ApiTags, @ApiBearerAuth, tài liệu cho upload file và chỉ bật /docs ở local. Bài sau mình sẽ giới thiệu về GraphQL trong NestJS, một cách khác để xây dựng API bên cạnh REST.
Đăng ký nhận tin.
Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!





0 Comments