better api

src/app.controller.ts

@@ -10,34 +10,39 @@ import {
 import { AppService, ScoreSheetData } from './app.service';
 import { Response } from 'express';
 import {
-  CxcyReturnMessage,
+  CxcyReturnMessageDto,
   CxcyReturnMessageLike,
-} from './messages/CxcyReturnMessage';
+} from './messages/CxcyReturnMessage.dto';
 import {
   ApiBadRequestResponse,
   ApiHeader,
   ApiInternalServerErrorResponse,
   ApiOkResponse,
+  ApiOperation,
   ApiQuery,
   ApiTags,
 } from '@nestjs/swagger';
 
 @Controller('api')
+@ApiTags('user')
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
   @Get('user/report.pdf')
-  @ApiTags('user')
+  @ApiOperation({
+    summary: '生成报告',
+    description: '生成学生的创新创业电子报告。',
+  })
   @ApiHeader({ name: 'Authorization', description: '用户 token' })
   @ApiQuery({ name: 'request_id', description: '请求 id，直接返回。' })
   @ApiOkResponse({ description: '成功，会直接提供文件下载。' })
   @ApiBadRequestResponse({
     description: '用户不存在或者没有登录。',
-    type: CxcyReturnMessage,
+    type: CxcyReturnMessageDto,
   })
   @ApiInternalServerErrorResponse({
     description: '报告生成过程中出现问题。',
-    type: CxcyReturnMessage,
+    type: CxcyReturnMessageDto,
   })
   async getPdf(
     @Headers('Authorization') userToken: string,
@@ -46,7 +51,7 @@ export class AppController {
     res: Response,
   ) {
     if (!userToken) {
-      new CxcyReturnMessage(
+      new CxcyReturnMessageDto(
         requestId,
         401,
         'Empty user token.',
@@ -63,7 +68,7 @@ export class AppController {
       return;
     }
     if (!data.data || !data.data.user) {
-      new CxcyReturnMessage(
+      new CxcyReturnMessageDto(
         requestId,
         401,
         'Some contents missing.',

src/app.service.ts

@@ -5,9 +5,9 @@ import * as fs from 'fs';
 import mdToPdf from 'md-to-pdf';
 import axios from 'axios';
 import {
-  CxcyReturnMessage,
+  CxcyReturnMessageDto,
   CxcyReturnMessageLike,
-} from './messages/CxcyReturnMessage';
+} from './messages/CxcyReturnMessage.dto';
 
 export interface NameWise {
   name: string;
@@ -52,7 +52,7 @@ export class AppService {
       return data;
     } catch (e) {
       this.log.error(`Failed to request backend ${url}: ${e.toString()}`);
-      return new CxcyReturnMessage(
+      return new CxcyReturnMessageDto(
         requestId,
         500,
         'backend request fail',

src/messages/CxcyReturnMessage.ts → src/messages/CxcyReturnMessage.dto.ts

@@ -7,11 +7,11 @@ export interface CxcyReturnMessageLike<T> {
   timestamp: number;
   request_id: string;
   status_code: number;
-  message: string;
-  data: T;
+  message?: string;
+  data?: T;
 }
 
-export class CxcyReturnMessage<T> implements CxcyReturnMessageLike<T> {
+export class CxcyReturnMessageDto<T> implements CxcyReturnMessageLike<T> {
   @ApiProperty({ description: '是否成功' })
   success: boolean;
   @ApiProperty({ description: '请求日期' })
@@ -21,14 +21,14 @@ export class CxcyReturnMessage<T> implements CxcyReturnMessageLike<T> {
   @ApiProperty({ description: '状态码' })
   public status_code: number;
   @ApiProperty({ description: '提示信息' })
-  public message: string;
+  public message?: string;
   @ApiProperty({ description: '返回内容' })
-  public data: T;
+  public data?: T;
   constructor(
     request_id: string,
     status_code: number,
-    message: string,
-    data: T,
+    message?: string,
+    data?: T,
   ) {
     this.request_id = request_id;
     this.status_code = status_code;