后端开发完接口后，需要给前端一份接口文档，描述有哪些接口，是 GET 还是 POST，有哪些参数，响应是什么。

但是写完代码后再去单独写一份这样的文档还是很麻烦的，并且改动接口之后也要同步去修改接口文档。

能不能自动生成 API 接口文档呢？

是可以的，就是这节要讲的 swagger。

我们新建个项目：

nest new swagger-test -p npm

安装 swagger 的包：

npm install --save @nestjs/swagger

然后在 main.ts 添加这样一段代码：

const config = new DocumentBuilder()
    .setTitle("Test example")
    .setDescription("The API description")
    .setVersion("1.0")
    .addTag("test")
    .build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("doc", app, document);

通过 DocumentBuilder 创建 config。

然后用 SwaggerModule.createDocument 根据 config 创建文档。

之后用 SwaggerModule.setup 指定在哪个路径可以访问文档。

跑起来试试：

npm run start:dev

访问 http://localhost:3000/doc 就可以看到 swagger 的 api 文档了：

和 DocumentBuilder 填的配置的对应关系如下：

现在只有一个接口，调用会返回 hello world：

点击 try it out，再点击 execute，就可以看到返回的响应体和 header：

我们在 AppController 加几个接口试试：

@Get('aaa')
aaa(@Query('a1') a1, @Query('a2') a2) {
    console.log(a1, a2);
    return 'aaa success';
}

@Get('bbb/:id')
bbb(@Param('id') id) {
    console.log(id);
    return 'bbb success';
}

@Post('ccc')
ccc(@Body('ccc') ccc) {
    console.log(ccc);
    return 'ccc success';
}

加了一个有 query 参数、一个有 param 参数、一个有 body 参数的接口。

刷新下可以看到，这几个接口都列出来了：

但是都没有 param 的描述和 response 的描述：

这时就需要我们手动标注了：

@ApiOperation({ summary: '测试 aaa',description: 'aaa 描述' })
@ApiResponse({
    status: HttpStatus.OK,
    description: 'aaa 成功',
    type: String
})
@Get('aaa')
aaa(@Query('a1') a1, @Query('a2') a2) {
    console.log(a1, a2);
    return 'aaa success';
}

给 aaa 接口添加 @ApiOperation 和 @ApiResponse 的装饰器。

这俩分别是指定这个接口的描述，接口的响应的。

再加上 @ApiQuery 来添加 query 参数的说明：

@ApiQuery({
    name: 'a1',
    type: String,
    description: 'a1 param',
    required: false,
    example: '1111',
})
@ApiQuery({
    name: 'a2',
    type: Number,
    description: 'a2 param',
    required: true,
    example: 2222,
})

刷新下，可以看到 swagger 文档里出现了这两个参数的说明：

点击 try it out 和 execute，就可以看到发送了请求并返回了响应：

这样，一个接口就描述完了：

通过 @ApiOperation 描述接口的信息，@ApiResponse 描述返回值信息，@ApiQuery 描述 query 参数信息。

就能生成对应的 swagger 文档：

我们接着来生成 bbb 接口的 swagger 文档：

这里用到的是 @ApiParam 而不是 @ApiQuery，其余部分一样：

@ApiOperation({ summary: '测试 bbb',description: 'bbb 描述' })
@ApiResponse({
    status: HttpStatus.OK,
    description: 'bbb 成功',
    type: String
})
@ApiParam({
    name: 'id',
    description: 'ID',
    required: true,
    example: 222,
})

刷新可以看到 bbb 接口的文档：

那如果 id 不合法的时候，我返回了一个 401 的响应呢？

那就再加一个 @ApiResponse

@ApiOperation({ summary: '测试 bbb',description: 'bbb 描述' })
@ApiResponse({
    status: HttpStatus.OK,
    description: 'bbb 成功',
    type: String
})
@ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: 'id 不合法'
})
@ApiParam({
    name: 'id',
    description: 'ID',
    required: true,
    example: 222,
})
@Get('bbb/:id')
bbb(@Param('id') id: number) {
    console.log(id);
    if(id !== 111) {
      throw new UnauthorizedException();
    }
    return 'bbb success';
}

刷新下，可以看到 swagger 文档标识出了这两种响应：

然后再来写 ccc 接口的文档：

ccc 接收的是请求体的参数，我们创建个 CccDto。

export class CccDto {
    aaa: string;
    bbb: number;
    ccc: Array<string>;
}

接收参数通过 dto 来接收，而返回值放在 vo 里：

@Post('ccc')
ccc(@Body('ccc') ccc: CccDto) {
    console.log(ccc);
    return {
      aaa: 111,
      bbb: 222
    };
}

创建个 vo 的 class：

export class CccVo {
    aaa: number;
    bbb: number;
}

返回值就可以改成这样了：

@Post('ccc')
ccc(@Body('ccc') ccc: CccDto) {
    console.log(ccc);

    const vo = new CccVo();
    vo.aaa = 111;
    vo.bbb = 222;
    return vo;
}

这里的 dto、vo 随便搜一下就能查到解释：

在 Nest 里要能清楚的区分 dto、vo、entity 的区别：

dto 是 data transfer object，用于参数的接收。

vo 是 view object，用于返回给视图的数据的封装。

而 entity 是和数据库表对应的实体类。

然后我们继续来写 ccc 接口的 swagger 文档。

很容易想到，body 的描述是通过 @ApiBody 的装饰器：

@ApiOperation({summary:'测试 ccc'})
@ApiResponse({
    status: HttpStatus.OK,
    description: 'ccc 成功',
    type: CccVo
})
@ApiBody({
    type: CccDto
})
@Post('ccc')
ccc(@Body('ccc') ccc: CccDto) {
    console.log(ccc);

    const vo = new CccVo();
    vo.aaa = 111;
    vo.bbb = 222;
    return vo;
}

刷新页面，你会看到除了接口外，还生成了俩 schema。

也就是说对象的响应会对应 swagger 的 schema。

只不过现在 CccDto、CccVo 的 schema 没有内容，这是因为我们还没有标注。

在 CccDto 加一下：

aaa、bbb、ccc 通过 @ApiProperty 标识下，并且 bbb 是 @ApiPropertyOptional，也就是可选，这个和 @ApiProperty({ required: false }) 等价。

aaa 可以传 enum 的值，取值范围是 a1、a2、a3。

同样，CccVo 也加一下：

import { ApiProperty } from "@nestjs/swagger";

export class CccVo {
    @ApiProperty({ name: "aaa" })
    aaa: number;

    @ApiProperty({ name: "bbb" })
    bbb: number;
}

刷新下，现在就可以看到 CccDto、CccVo 的 schema 有属性了：

其中 bbb 是没有 * 的，代表可不传。

上面的接口部分也有了请求和响应的示例：

点下 try it out，可以自己编辑请求体：

然后点击 execute 就可以看到响应的内容和 header：

服务端也确实接收到了这个请求：

可以用 swagger 来方便的测试接口。

此外，还可以通过 @ApiTags 来给接口分组：

比如 controller 是 xxx 开头的，那可以用 @ApiTags 来分组到 xxx。

显示的时候，就会把这个 controller 的接口分到一个组下：

也可以添加在 handler 上：

比如把 aaa、bbb 接口分到 xxx-get 的组。

那显示的时候就会把这俩接口分出来：

当接口多了之后，分组还是很有必要的。

回过头来，再讲下 @ApiProperty，其实它还有很多属性：

import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";

export class CccDto {
    @ApiProperty({
        name: "aaa",
        enum: ["a1", "a2", "a3"],
        maxLength: 30,
        minLength: 2,
        required: true,
    })
    aaa: string;

    @ApiPropertyOptional({
        name: "bbb",
        maximum: 60,
        minimum: 40,
        default: 50,
        example: 55,
    })
    bbb: number;

    @ApiProperty({ name: "ccc" })
    ccc: Array<string>;
}

比如 required、minium、maximum、default、maxLength 等。

此外，很多接口是需要登录才能访问的，那如何限制呢？

swagger 也提供了这方面的支持。

常用的认证方式就是 jwt、cookie。

分别在 aaa、bbb、ccc 接口添加 @ApiBearerAuth、@ApiCookieAuth、@ApiBasicAuth

然后在 main.ts 里添 3 种认证方式的信息：

const config = new DocumentBuilder()
    .setTitle("Test example")
    .setDescription("The API description")
    .setVersion("1.0")
    .addTag("test")
    .addBasicAuth({
        type: "http",
        name: "basic",
        description: "用户名 + 密码",
    })
    .addCookieAuth("sid", {
        type: "apiKey",
        name: "cookie",
        description: "基于 cookie 的认证",
    })
    .addBearerAuth({
        type: "http",
        description: "基于 jwt 的认证",
        name: "bearer",
    })
    .build();