Swagger SpringBoot x Javascript 使用教程（Springdoc x Swagger Codegen）

SpringBoot

SpringBoot 端使用的库为 SpringDoc。注意不要用 SpringFox，SpringFox 已经停止更新了，且不支持 3.x。

访问 SpringDoc 官网，复制 Maven 依赖。例如现在最新的版本为：

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.6.0</version>
   </dependency>

然后刷新仓库，启动服务器，访问 http://127.0.0.1:8080/swagger-ui.html ，检查是否能正常使用。

具体在代码中的使用方法可以参照这篇文章。文章中的使用的版本较旧，新版相对于旧版有很多命名变化，具体参考 Springdoc 的 Migrating from SpringFox。

JavaScript

在这里下载 Swagger Codegen，用于生成前端代码。（注意不是在 Release 里，是在 README 的 Maven 仓库地址里。）
注意 Swagger 和 Swagger Codegen 的版本要对应，2.x 和 3.x 不能混用。这里我用的是 3.x 的版本。

然后就是调用 Swagger Codegen 生成代码了。生成命令为：

java -jar swagger-codegen-cli-3.0.57.jar generate -i http://localhost:8080/v3/api-docs -l javascript -c config.json

生成结果是一个 NPM 项目，不方便直接在现有项目使用。因此需要先打包，然后在项目中安装。

config.json 为配置文件，具体可以设置的参数可以通过执行 java -jar .\swagger-codegen-cli-3.0.57.jar config-help -l javascript 查看。其中比较重要的两个参数为：

• projectName：项目名称，也是最终得到的 NPM 包名
• usePromises：是否使用 Promise 风格。默认为回调风格。

为了简化过程，我写了一个 PowerShell 脚本：

# 创建临时文件夹
mkdir api
cd api
# 生成
java -jar ..\swagger-codegen-cli-3.0.57.jar generate -i http://localhost:8080/v3/api-docs -l javascript -c ..\config.json
# 打包
npm pack
# 重新安装
cd ..
npm uninstall <包名>
npm install --save ./api/<打包结果文件>
# 清除文件
rm -r -fo api
rm -r -fo .\node_modules\.cache

执行之前需要前关闭运行的项目。