开发背景

看过我以前文章的朋友，一定都知道，我一直在写一个个人博客，后台接口经历过这么几个阶段。

Express + MySQL开发
Express + MongoDB开发
EggJS + MySQL开发
NestJS + MySQL开发

差不多也有三年时间了吧，从去年接触NestJS以来，发现真是个好东西，后台接口一定得需要一个接口文档，以前我总是自己手写Markdown来编写接口文档，通过postman来进行接口测试，后来发现效率有点低，而且需要不断做重复的工作量，属实有点累赘，直到后来我了解到了丝袜哥(Swagger)，发现真好用，写接口的同时，文档也给写了，还能测试接口。今天就来分享一下在NestJS中怎样使用Swagger。

安装依赖

使用Swagger之前，我们需要先安装指定依赖。

npm i @nestjs/swagger

这里贴一下文档地址。

封装类

这里我在src/lib目录下新建一个Swagger类，命名Swagger.ts。

引入所需

首先来引入所需要的依赖。

import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";

定义骨架

把一个类的基础骨架实现。

export class Swagger {
  constructor() {}
}

编写类

在这个类中，我们暂且需要五个私有属性：

app：指的是Module，需要把这个Swagger挂载在哪个Module下。
title：文档标题。
description：文档描述。
version：文档版本号。
url：文档生成的地址。

export class Swagger {
  private app = null;
  private title = "API文档";
  private description = "webxue的API文档";
  private version = "1.0";
  private url = "/doc";
  
  constructor() {}
}

然后在constructor中接收参数，并赋值给私有属性：

export class Swagger {
  // ...
  
  constructor(options) {
    this.app = option.app;
    if (option.title) this.title = option.title;
    if (option.description) this.description = option.description;
    if (option.version) this.version = option.version;
    if (option.url) this.url = option.url;
  }
}

其中，这里的app为必传参数，其余都为选传。

接下来编写生成Swagger的方法：

build() {
  const swaggerOptions = new DocumentBuilder()
    .setTitle(this.title)
    .setDescription(this.description)
    .setVersion(this.version)
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(this.app, swaggerOptions);
  SwaggerModule.setup(this.url, this.app, document);
}

首先实例化DocumentBuilder
调用实例下的setTitle方法来设置文档标题
调用实例下的setDescription方法来设置文档描述
调用实例下的setVersion方法来设置文档版本号
调用实例下的addBearerAuth方法来添加文档Bearer 鉴权
调用实例下的build方法来构建文档
调用SwaggerModule的createDocument方法，将NestFactory创建的主程序app和Swagger参数传入
调用SwaggerModule的setup方法设置文档访问地址为/doc

到这里为止，Swagger类就封装完成了，贴一张官方文档的图：

image.png

如何使用

在src/main.ts中引入Swagger类。

import { Swagger } from './lib/Swagger';

在bootstrap启动程序中调用Swagger类的build方法生成文档。

(async function bootstrap() {
  // 加载主模块到Nest工厂
  const app = await NestFactory.create(AppModule);
  // ...

  // 构建swagger
  new Swagger({ app }).build();

  // ...
})();

接下来我们启动服务之后，访问/doc就可以看到接口文档了。

image.png

结语

这篇文章只是浅浅的介绍了一下怎么在NestJS中引入Swagger，至于如何使用，文档写的比较详细，后面如果有时间，或者有朋友需要的话，可以在文章下方评论，将介绍一篇如何使用Swagger的文章。

我是一名前端程序员，但不止于前端，如果你觉得哪里写的欠妥，或者你有更好的方法，欢迎评论区讨论，一起学习，一起进步~