NestJs 结合 swagger 文档并自动导入 apifox，再也不用担心前端说接口调不通了

Moment
2,179 阅读4分钟

文章开始之前分享两个开源项目，会一直维护的，欢迎 star，如果你感兴趣或者想参与学习，可以加我微信 yunmz777，最近也在找工作 ing，欢迎内推......

浪费你两秒钟时间，我们正文开始！！！

Swagger 是一套开源软件工具，用于设计、构建、记录和使用 RESTful Web 服务。它允许开发人员和团队从设计到开发阶段，在整个 API 生命周期中定义、管理和维护 API。Swagger 现在是 OpenAPI 规范的一部分，这是一个用于 API 描述的广泛采用的标准格式。

在接下来的内容中我们将来学习一下在 NestJs 中结合 swagger 实现一个 api 文档，并在 apifox 中自动导入。

nest 中使用

要想使用，首先我们需要在项目中安装：

pnpm add @nestjs/swagger

之后我们需要在项目的入口文件中导入，如下代码所示：

import { NestFactory } from "@nestjs/core";
import {
  FastifyAdapter,
  NestFastifyApplication,
} from "@nestjs/platform-fastify";
import { ValidationPipe } from "@nestjs/common";
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ bodyLimit: 50 * 1024 * 1024 }),
    {
      snapshot: true,
    }
  );

  app.setGlobalPrefix("api/v1/");

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      transform: true,
    })
  );

  const config = new DocumentBuilder()
    .setTitle("接口文档")
    .setVersion("1.0")
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup("docs", app, document, {
    jsonDocumentUrl: "openApiJson",
  });

  await app.listen(8080, "0.0.0.0");
}

bootstrap();

docs 这是 API 文档将被托管的路由路径。在这个例子中，你可以通过访问 /docs 来查看 Swagger UI。

jsonDocumentUrl 这是一个可选配置，允许你指定一个 URL 路径，通过该路径可以获取到 OpenAPI 规范的原始 JSON 文件。在这个例子中，这个路径设置为 'openApiJson'，意味着你可以通过访问 /openApiJson 来直接获取 API 的 OpenAPI JSON 规范。

现在这样子我们的 swagger 文档有了，我们打开浏览器 http://localhost:8080/docs 就可以看到效果了。

结合@nestjs/swagger 编写更详细的文档

@nestjs/swagger 包提供了多种装饰器，用于增强 NestJS 应用中的 Swagger 文档生成。这些装饰器主要用于定义 API 元数据、参数类型、响应类型和其他文档相关的配置。使用这些装饰器可以帮助自动生成准确和详细的 API 文档。

@ApiTags(...)

用于为控制器或特定路由方法添加标签，这些标签在 Swagger UI 中作为分类显示。

@ApiTags("users")
@Controller("users")
export class UsersController {
  @Get()
  findAll() {
    // 方法实现
  }
}

@ApiOperation({ summary: '...' })

用于提供单个路由操作的简短描述。它通常用于详细说明一个具体的 API 功能。

@Get()
@ApiOperation({ summary: '查找所有用户' })
findAll() {
  // 方法实现
}

@ApiResponse({ status: ..., description: ..., type: ... })

定义方法的响应类型及状态码。type 选项用于指定返回数据的类型，这对生成精确的响应模型极为重要。

@Get()
@ApiResponse({
  status: 200,
  description: 'Success',
  type: User
})
findAll() {
  // 方法实现
}

@ApiParam({ name: ..., description: ..., required: ..., type: ... })

用于描述路径参数的细节，例如在 URL 中的 {id}。

@Get(':id')
@ApiParam({ name: 'id', description: 'User ID', required: true, type: Number })
findOne(@Param('id') id: string) {
  // 方法实现
}

@ApiBody({ description: ..., type: ..., required: ... })

用于定义 API 请求体的细节。它非常有用，特别是对于 POST 和 PUT 请求。

@Post()
@ApiBody({ description: 'User payload', type: CreateUserDto, required: true })
create(@Body() createUserDto: CreateUserDto) {
  // 方法实现
}

@ApiQuery({ name: ..., description: ..., required: ..., type: ... })

用于描述查询参数，例如在 GET 请求中通过 URL 传递的参数。

@Get()
@ApiQuery({ name: 'role', description: 'Filter by role', required: false, type: String })
findByRole(@Query('role') role: string) {
  // 方法实现
}

@ApiProperty(...)

用于 DTO 类中的属性，以提供关于字段的具体信息，如类型、描述、是否必需等。

export class CreateUserDto {
  @ApiProperty({ description: "用户名", example: "Moment" })
  name: string;

  @ApiProperty({ description: "用户邮箱", example: "moment@qq.com" })
  email: string;
}

这些装饰器共同工作，能够为你的 NestJS 应用生成丰富、结构化且易于导航的 API 文档。这不仅有助于开发者理解和使用 API，而且通过这种自动化的文档方式，可以大大减少手动编写和维护 API 文档的工作。

接口示例

接下来我们定义一下这样的代码，如下所示： 20240429142132转存失败，建议直接上传图片文件

之后我们打开 swagger ui 网站来查看效果，如下图所示：

20240429142405

它首先给我们分好了类，然后我们再查看其中一个接口：

20240429142452

这些编写好的规则都能够直接在页面上显示。

如果你想使用 apifox 来调试接口的话，首先我们需要创建一个项目，然后使用 url 的方式来导入接口的 json 文件：

20240429142612

之后点击提交即可。

20240429142714

你会看到 apifox 上查看可能会更好查看，参数和返回值都是可以看见的，这就实现了我们的 swagger 文档和 apifox 实现了自动更新的功能了。如果你想定时更新的话就可以点击这里了：

20240429142901

总结

通过使用 swagger 文档，结合 apifox，基本不用我们编写接口文档了，方便又快捷，而且 apifox 也能帮我们来生成测试数据，更方便了。

avatar
文章
阅读
粉丝