some desc

nest-cli.json

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

src/app.controller.ts

@@ -19,6 +19,7 @@ import {
   ApiInternalServerErrorResponse,
   ApiOkResponse,
   ApiQuery,
+  ApiTags,
 } from '@nestjs/swagger';
 
 @Controller('api')
@@ -26,11 +27,18 @@ export class AppController {
   constructor(private readonly appService: AppService) {}
 
   @Get('user/report.pdf')
+  @ApiTags('user')
   @ApiHeader({ name: 'Authorization', description: '用户 token' })
   @ApiQuery({ name: 'request_id', description: '请求 id，直接返回。' })
   @ApiOkResponse({ description: '成功，会直接提供文件下载。' })
-  @ApiBadRequestResponse({ description: '用户不存在或者没有登录。' })
-  @ApiInternalServerErrorResponse({ description: '报告生成过程中出现问题。' })
+  @ApiBadRequestResponse({
+    description: '用户不存在或者没有登录。',
+    type: CxcyReturnMessage,
+  })
+  @ApiInternalServerErrorResponse({
+    description: '报告生成过程中出现问题。',
+    type: CxcyReturnMessage,
+  })
   async getPdf(
     @Headers('Authorization') userToken: string,
     @Query('request_id') requestId: string,
@@ -38,9 +46,12 @@ export class AppController {
     res: Response,
   ) {
     if (!userToken) {
-      res
-        .status(401)
-        .json(new CxcyReturnMessage(requestId, 401, 'Empty user token.', null));
+      new CxcyReturnMessage(
+        requestId,
+        401,
+        'Empty user token.',
+        null,
+      ).writeResponse(res);
       return;
     }
     const data: CxcyReturnMessageLike<any> = await this.appService.getUserData(
@@ -52,11 +63,12 @@ export class AppController {
       return;
     }
     if (!data.data || !data.data.user) {
-      res
-        .status(500)
-        .json(
-          new CxcyReturnMessage(requestId, 401, 'Some contents missing.', null),
-        );
+      new CxcyReturnMessage(
+        requestId,
+        401,
+        'Some contents missing.',
+        null,
+      ).writeResponse(res);
       return;
     }
     const userData = data.data.user;

src/main.ts

@@ -10,6 +10,7 @@ async function bootstrap() {
     .setTitle('cxcy-scoresheet')
     .setDescription('创新创业报告生成模块')
     .setVersion('1.0')
+    .addTag('user', '用户接口')
     .build();
 
   const document = SwaggerModule.createDocument(app, documentConfig);

src/messages/CxcyReturnMessage.ts

 import moment from 'moment';
+import { ApiProperty } from '@nestjs/swagger';
+import { Response } from 'express';
 
 export interface CxcyReturnMessageLike<T> {
   success: boolean;
@@ -10,15 +12,33 @@ export interface CxcyReturnMessageLike<T> {
 }
 
 export class CxcyReturnMessage<T> implements CxcyReturnMessageLike<T> {
+  @ApiProperty({ description: '是否成功' })
   success: boolean;
+  @ApiProperty({ description: '请求日期' })
   timestamp: number;
+  @ApiProperty({ description: '请求中的请求 ID。' })
+  public request_id: string;
+  @ApiProperty({ description: '状态码' })
+  public status_code: number;
+  @ApiProperty({ description: '提示信息' })
+  public message: string;
+  @ApiProperty({ description: '返回内容' })
+  public data: T;
   constructor(
-    public request_id: string,
-    public status_code: number,
-    public message: string,
-    public data: T,
+    request_id: string,
+    status_code: number,
+    message: string,
+    data: T,
   ) {
+    this.request_id = request_id;
+    this.status_code = status_code;
+    this.message = message;
+    this.data = data;
     this.success = status_code < 400;
     this.timestamp = moment().unix();
   }
+
+  writeResponse(res: Response) {
+    res.status(this.status_code).json(this);
+  }
 }