Nest集成Swagger并部署至YAPI

简介: Nest集成Swagger并部署至YAPI

前言


前几天在项目中集成了swagger,一切准备就绪打算将其部署到服务器时发现并不顺利,访问的时候页面白屏,由于我的nest项目采用的是单文件部署,互联网上没有找到相关的解决方案,于是我就成了第一个吃螃蟹的人。


经过一番折腾后,终于解决了这个问题,本文就跟大家分享下我的解决方案,欢迎各位感兴趣的开发者阅读本文。


集成Swagger


首先,我们通过yarn安装三个依赖包,如下所示:


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


安装完成后,我们打开项目的入口文件main.ts添加如下所示的代码:


import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
async function bootstrap() {
  // ****  其它代码省略  ****
  const config = new DocumentBuilder()
    .setTitle("nest-demo")
    .setDescription("nest-demo项目的API使用文档")
    .setVersion("1.0.0")
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup("api", app, document);
}


接下来,我们启动项目,在浏览器访问http://127.0.0.1:3000/api,显示的界面如下所示:


  • default选项列出了我们项目中的所有接口


640.png

                               image-20220317211550995


通过注解编写接口文档


在@nestjs/swagger库中,它提供了丰富的依赖供我们使用, 为我们生成友好的接口文档,接下来我们列举几个较为常用的注解:


  • @ApiTags注解,用于对controller层进行描述。
  • @ApiOperation注解,用于对controller中的具体接口进行描述。
  • @ApiProperty注解,用于对dto层的参数进行描述。
  • @ApiResponse注解,用于对接口的返回数据进行描述。


关于上述各个注解的具体使用方法可参考我的项目代码,如下所示:


  • AppController.ts[1]
  • AppDto.ts[2]
  • ResultVO[3]


经过上述配置后 ,最终访问效果如下所示:


640.png

                               image-20220317224923516


有关swagger注解的更多使用方法请移步:OpenAPI (Swagger)[4]


部署至服务器


接下来,我们要做的就是将项目打包部署到服务器了,本项目采用的是单文件构建法,对此不了解的开发者请移步:Nest项目部署的最佳方式[5]


构建时遇到的问题


因为集成了swagger进来,在打包时终端报错了ERROR in ./node_modules/@nestjs/mapped-types/dist/type-helpers.utils.js 69:27-63 Module not found: Error: Can't resolve 'class-transformer/storage' in ...

经过一番查找后,在mapped-types仓库的Issues[6]中找到了答案,需要在webpack.config.js中的lazyImports中加入class-transformer/storage,打包的时候即可将其忽略,部分代码如下所示,完整代码请移步:


module.exports = {
  entry: "./src/main",
  target: "node",
  // ** 其他配置代码省略 **
  plugins: [
    // 需要进行忽略的插件
    new webpack.IgnorePlugin({
        checkResource(resource) {
        const lazyImports = [
          "@nestjs/microservices",
          "@nestjs/microservices/microservices-module",
          "@nestjs/websockets/socket-module",
          "cache-manager",
          "class-validator",
          "class-transformer",
          "class-transformer/storage"
        ];
    })
}

完整代码请移步:webpack.config.js[7]


部署时遇到的问题


我们将项目部署到服务器,启动后,在浏览器通过127.0.0.1:3000/api访问swagger时发现页面一片空白,打开控制台后发现它的一些资源文件404了。


640.png

                          image-20220318072947623


这可真是个棘手的问题,直觉告诉我肯定是因为我配置了单文件部署才导致的,我在求助了很多人,查了很多资料后,发现他们都没像我这么玩过,他们都是在服务器上npm install依赖来跑nest项目的。


真是糟了个大糕🤡,我成了第一个吃螃蟹的人,前面一片蓝海等着我去探索。


经过一番思考后,应该是因为webpack把所有依赖都打包进main.js了,swagger-ui引用的文件应该是相对路径的,所以才导致了404问题,抱着这个疑问,我打开了swagger-ui-express的源码,在index.js中发现了猫腻:它果然是引入的相对路径。


640.png

                            image-20220318074256928


既然是相对路径,它自己的包下面又没有这个文件,那么它肯定是从别的包引入的。


640.png

                            image-20220318074447502


继续查阅源码后,我发现它还require了一个swagger-ui-dist


640.png

                            image-20220318074604930


果然,它所依赖的资源包都在这个目录下,他为什么要这么做呢?我又抱着疑问打开了swagger-ui仓库,在docs/usage/installation.md[8]中它讲述了原因,提供了webpack的配置方案。


640.png

                          image-20220318075453246


打开链接所指向的项目后,在webpack的配置文件中我看到了copy-webpack-plugin插件,此时我茅塞顿开,它的做法就是将swagger-ui-dist的文件拷贝到dist下,这样就解决了它相对路径找不到文件的问题。


方案有了,那么就可以愉快的写出代码了,如下所示:


const CopyWebpackPlugin = require("copy-webpack-plugin");
module.exports = {
  entry: "./src/main",
  target: "node",
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        // 拷贝swagger相关的文件
        {
          from: __dirname + "/node_modules/swagger-ui-dist/",
          to: "./"
        }
      ]
    })
  ]
}


重新构建后,我们发现dist目录下多了swagger-ui-dist的文件,我们启动项目,重新在浏览器发现已经能正常看到swagger的界面了。


640.png

                                image-20220318111124109


细心的开发者可能发现swagger-ui-dist目录下有很多无用文件,污染了我们的dist目录,我们需要将这些无用的文件在打包后清理掉。


![image-20220318112446885](/Users/likai/Library/Application Support/typora-user-images/image-20220318112446885.png)


接下来就该clean-webpack-plugin插件登场了,我们在webpack的配置文件中加入下述代码:


  • cleanAfterEveryBuildPatterns 意为在构建完成之后删除文件


const { CleanWebpackPlugin } = require("clean-webpack-plugin");
module.exports = {
  entry: "./src/main",
  target: "node",
  plugins: [
    // ** 其它代码省略 **
    // 删除多余的文件
    new CleanWebpackPlugin({
      cleanAfterEveryBuildPatterns: [
        __dirname + "/dist/*.html",
        __dirname + "/dist/*.map",
        __dirname + "/dist/*.md",
        __dirname + "/dist/*.json",
        __dirname + "/dist/index.js",
        __dirname + "/dist/LICENSE",
        __dirname + "/dist/NOTICE"
      ]
    })
  ]
}


现在dist目录看起来就舒服多了😼


640.png

                                  image-20220318114857681

注意:copy-webpack-plugin、clean-webpack-plugin需要用yarn自行安装到devDependencies依赖中。

完整代码请移步:webpack.config.js[9]


部署至YAPI


最后,我们在yapi的数据管理模块,导入swagger数据过来,本以为很顺利,结果它报错:返回数据格式不是JSON。


640.png

                                 image-20220318113759221


翻阅文档后,我找到了方案[10],原来是要在地址后面加-json


加了之后,就能顺利的导入到yapi了,大功告成🤗


640.png

                               image-20220318114103459


做第一个吃螃蟹的人太难了,为了解决这个问题,我在浏览器已经不知不觉的开了这么多标签页了🌚


640.png

                                   image-20220318114447903


项目代码


本文所使用的完整代码,请移步项目的GitHub仓库:nest-project[11]


写在最后


至此,文章就分享完毕了。


我是神奇的程序员,一位前端开发工程师。


如果你对我感兴趣,请移步我的个人网站[12],进一步了解。

  • 文中如有错误,欢迎在评论区指正,如果这篇文章帮到了你,欢迎点赞和关注😊
  • 文中链接可从文末参考资料中获取
相关文章
|
6月前
|
监控 前端开发 测试技术
如何实现前端工程化的持续集成和持续部署?
通过以上步骤,可以建立一套完整的前端工程化 CI/CD 流程,实现前端代码从开发、测试、构建到部署的全自动化,提高开发效率、保证代码质量,快速响应用户需求和市场变化。
|
16天前
|
弹性计算 机器人 应用服务中间件
一键部署开源Qwen3并集成到钉钉、企业微信
Qwen3系列模型现已正式发布并开源,包含8款“混合推理模型”,其中涵盖两款MoE模型(Qwen3-235B-A22B与Qwen3-30B-A3B)及六个Dense模型。阿里云计算巢已支持Qwen3-235B-A22B和Qwen3-32B的私有化部署,用户可通过计算巢轻松完成部署,并借助AppFlow集成至钉钉机器人或企业微信。文档详细介绍了从模型部署、创建应用到配置机器人的全流程,帮助用户快速实现智能助手的接入与使用。
一键部署开源Qwen3并集成到钉钉、企业微信
|
8天前
|
JSON 缓存 并行计算
NVIDIA 实现通义千问 Qwen3 的生产级应用集成和部署
阿里巴巴近期开源了通义千问Qwen3大语言模型(LLM),包含两款混合专家模型(MoE)235B-A22B与30B-A3B,以及六款稠密模型(Dense)从0.6B到32B不等。开发者可基于NVIDIA GPU使用TensorRT-LLM、Ollama、SGLang、vLLM等框架高效部署Qwen3系列模型,实现快速词元生成和生产级应用开发。
|
2月前
|
JSON Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
80 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
2月前
|
缓存 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
89 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
|
3月前
|
人工智能 Kubernetes jenkins
容器化AI模型的持续集成与持续交付(CI/CD):自动化模型更新与部署
在前几篇文章中,我们探讨了容器化AI模型的部署、监控、弹性伸缩及安全防护。为加速模型迭代以适应新数据和业务需求,需实现容器化AI模型的持续集成与持续交付(CI/CD)。CI/CD通过自动化构建、测试和部署流程,提高模型更新速度和质量,降低部署风险,增强团队协作。使用Jenkins和Kubernetes可构建高效CI/CD流水线,自动化模型开发和部署,确保环境一致性并提升整体效率。
|
2月前
|
Java Maven 微服务
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的 maven 依赖
在项目中使用Swagger2工具时,需导入Maven依赖。尽管官方最高版本为2.8.0,但其展示效果不够理想且稳定性欠佳。实际开发中常用2.2.2版本,因其稳定且界面友好。以下是围绕2.2.2版本的Maven依赖配置,包括`springfox-swagger2`和`springfox-swagger-ui`两个模块。
53 0
|
2月前
|
前端开发 Java API
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档—— Swagger 简介
第6课介绍了在Spring Boot中集成Swagger2以展示在线接口文档的方法。随着前后端分离架构的发展,API文档成为连接前端与后端开发的重要纽带。然而,代码更新频繁导致文档难以同步维护,Swagger2解决了这一问题。通过Swagger,在线API文档不仅方便了接口调用方查看和测试,还支持开发者实时测试接口数据。本文使用Swagger 2.2.2版本,讲解如何在Spring Boot项目中导入并配置Swagger2工具,从而高效管理接口文档。
114 0
|
6月前
|
jenkins Devops Java
DevOps实践:Jenkins在持续集成与持续部署中的价值
【10月更文挑战第27天】在快速发展的软件开发领域,DevOps实践日益重要。Jenkins作为一款流行的开源自动化服务器,在持续集成(CI)和持续部署(CD)中扮演关键角色。本文通过案例分析,探讨Jenkins在Java项目中的应用,展示其自动化构建、测试和部署的能力,提高开发效率和软件质量。
158 2
|
3月前
|
弹性计算 人工智能 应用服务中间件
一键部署开源DeepSeek并集成到企业微信
DeepSeek近期发布了两款先进AI模型V3和R1,分别适用于通用应用和推理任务。由于官方API流量过大,建议通过阿里云的计算巢进行私有化部署,以确保稳定使用。用户无需编写代码即可完成部署,并可通过AppFlow轻松集成到钉钉、企业微信等渠道。具体步骤包括选择适合的机器资源、配置安全组、创建企业微信应用及连接流,最后完成API接收消息配置和测试应用。整个过程简单快捷,帮助用户快速搭建专属AI服务。
一键部署开源DeepSeek并集成到企业微信