nodejs企业级开发框架nest学习总结 - 7.NestJS入门swagger，快速搭建restfulApi文档

swagger

*由于最近新版@nestjs/swagger4.*的更新，使用的注解也发生了一些改动，具体可以查看

@nestjs/swagger官方地址

swagger：一个功能强大的高清格式来描述RESTful API。Nest提供了专用的模块来使用它

1. 安装swagger

yarn add @nestjs/swagger swagger-ui-express --save

如果使用fastify，则必须安装fastify-swagger而不是swagger-ui-express：

yarn add @nestjs/swagger fastify-swagger --save

2.配置文档格式信息

// main.ts 中配置
import {
    NestFactory } from '@nestjs/core';
import {
    NestExpressApplication } from '@nestjs/platform-express';
// api文档插件
import {
    SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
const app = await NestFactory.create<NestExpressApplication>(AppModule);
// DocumentBuilder是一个辅助类，有助于结构的基本文件SwaggerModule。它包含几种方法，可用于设置诸如标题，描述，版本等属性。
  const options = new DocumentBuilder()
    .setTitle('nest入门接口标题')
    .setDescription('使用nest书写的常用性接口') // 文档介绍
    .setVersion('1.0.0') // 文档版本
    .addTag('用户,安全') // 每个tag标签都可以对应着几个@ApiUseTags('用户,安全') 然后被ApiUseTags注释，字符串一致的都会变成同一个标签下的
    // .setBasePath('http://localhost:5000')
    .build();
  // 为了创建完整的文档（具有定义的HTTP路由），我们使用类的createDocument()方法SwaggerModule。此方法带有两个参数，分别是应用程序实例和基本Swagger选项。
  const document = SwaggerModule.createDocument(app, options);
   // 最后一步是setup()。它依次接受（1）装入Swagger的路径，（2）应用程序实例, （3）描述Nest应用程序的文档。
  SwaggerModule.setup('/api', app, document);
   await app.listen(5000);

1.先通过DocumentBuilder实例来设置文档的配置选项，例如版本、标题、文档介绍、多个标签等

2.然后通过@nestjs/swagger模块提供的SwaggerModule的createDocument方法创建文档，传递整个app(应用程序实例)为第一个参数，第二个参数就是1配置号的文档选项

3.第三步是通过SwaggerModule的setup方法出口创建文档的url,它依次接受（1）装入Swagger的路径，（2）应用程序实例, （3）描述Nest应用程序的文档。

这时候会变成默认的配置文档选项

这时候启动默认初始化的项目，访问http://localhost:3000/api/

然后返回正确的状态和数据，文档都无需自己手写，减少不少的文档编辑量
定义控制器时，SwaggerModule寻找所有的使用@Body()，@Query()以及@Param()在路由处理器装饰。因此，可以创建有效的文档。

2.1 我们创建user文件夹，存放user相关的module，controller，service,代码如下:

// user.service.ts
import {
    Injectable } from '@nestjs/common';

@Injectable()
export class UserService {
   
    public getUser(id: string): string {
   
        return `用户的id:${
     id}`;
    }
}

// user.controller.ts
import {