nestjs配置swagger教程

本文记录如何在nestjs框架下配置swagger。OpenAPI是一个与语言无关的RESTful API定义说明,Nest提供了一个专有的模块来利用装饰器生成类似声明。

安装

npm install --save @nestjs/swagger swagger-ui-express

引导

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./modules/app.module";
import { Logger } from "@nestjs/common";
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('api-collect')
    .setDescription('API文档')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('doc', app, document);

  await app.listen(3001);
}

bootstrap().then(() => {
  Logger.log("启动成功");
});

这里主要引入了两个模块,SwaggerModuleDocumentBuilder。其中DocumentBuilder建立一个遵循OpenAPI 标准的基础文档。它提供了不同的方法来配置类似标题、描述、版本等信息属性。

(SwaggerModule#createDocument()方法返回)是一个遵循OpenAPI文档的序列化对象。除了HTTP,你也可以以JSON/YAML文件格式保存和使用它。

SwaggerModule.setup(‘api’, app, document);

此行代码标记你的文档最终挂载的路径。

运行体验

nestjs swagger

此时我们就可以看到熟悉的swagger界面啦。

类型和参数

如果我们想设置swagger对应的参数请求类型,那么也可以使用它的反射来创建响应模型。

使用ts声明一个参数请求dto

export class ParamsDto {
  params?: string[];
}
```typescript

接口上声明对应的入参

```typecript
import { Body, Controller, Post, Query } from "@nestjs/common";
import { SqlService } from "../service/sql.service";
import { CodeDto } from "../entity/code.dto";
import { ParamsDto } from "../entity/params.dto";
import { PathDto } from "../entity/path.dto";

@Controller("api-collect")
export class SqlController {
  constructor(private readonly sqlService: SqlService) {
  }

  @Post("/execute-by-path")
  executeByPath(@Query() pathDto: PathDto, @Body() paramsDto: ParamsDto) {
    return this.sqlService.executeSqlByPath(pathDto.path, paramsDto.params);
  }

  @Post("/execute-by-code")
  executeByCode(@Query() codeDto: CodeDto, @Body() paramsDto: ParamsDto) {
    return this.sqlService.executeSqlByCode(codeDto.code, paramsDto.params);
  }
}

激活swagger ts类型扫描插件(Nestjs框架自带)

swagger ts类型扫描

激活此插件后

ts的枚举类型会作为swagger的入参枚举类型,可选变量也会生成对应的required字段

插件会自动扫描[‘.dto.ts’, ‘.entity.ts’]后缀的类实体声明

效果预览

Nest js swagger

Description

版权声明: (https://www.thinkmoon.cn/post/976)
本文首发于指尖魔法屋-nestjs配置swagger教程
转载或引用必须申明原指尖魔法屋来源及源地址!