如何在Ubuntu上实现Swagger自动化生成

在Ubuntu上实现Swagger自动化生成的分步指南

一、前置准备：安装必要工具

在Ubuntu上实现Swagger自动化生成前，需先安装以下基础工具：

1. 安装Node.js和npm：Swagger UI、Swagger Editor等工具依赖Node.js环境。通过以下命令安装稳定版：

   curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

   安装完成后，验证版本：node -v、npm -v（建议使用Node.js 14及以上版本）。

二、选择自动化生成方案（根据技术栈选择）

Swagger自动化生成的核心是通过代码注解或构建流程集成实现文档与代码同步。以下是常见场景的解决方案：

方案1：Java项目（Spring Boot）—— 使用Springfox/Springdoc

Spring Boot项目推荐使用Springdoc OpenAPI（替代传统的Springfox，支持OpenAPI 3.0+，维护更活跃），通过注解自动生成文档。

1. 添加依赖：在pom.xml（Maven）中添加以下依赖：

   <dependency>
       <groupId>org.springdocgroupId>
       <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
       <version>2.5.0version> 
   dependency>
   

   （若使用Gradle，在build.gradle中添加：implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'）。
2. 配置注解：在Controller类和方法上添加Swagger注解，丰富文档细节：

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.Parameter;
   import io.swagger.v3.oas.annotations.tags.Tag;
   
   @Tag(name = "用户管理", description = "用户相关接口")
   @RestController
   @RequestMapping("/api/users")
   public class UserController {
       
       @Operation(summary = "获取用户列表", description = "分页返回所有用户信息")
       @GetMapping
       public ResponseEntity> listUsers(
           @Parameter(description = "页码", example = "1") @RequestParam(defaultValue = "1") int page,
           @Parameter(description = "每页数量", example = "10") @RequestParam(defaultValue = "10") int size) {
           // 业务逻辑
           return ResponseEntity.ok(userService.list(page, size));
       }
   }
   

3. 访问文档：启动Spring Boot应用后，直接访问http://localhost:8080/swagger-ui.html（Springdoc默认路径），即可看到自动生成的交互式文档。

方案2：通用API项目—— 使用Swagger Codegen/OpenAPI Generator

若已有OpenAPI规范文件（swagger.yaml/openapi.json），可通过Swagger Codegen或OpenAPI Generator（推荐，支持更多语言和框架）自动生成文档或客户端代码。

1. 安装OpenAPI Generator：通过npm全局安装：

   sudo npm install -g @openapitools/openapi-generator-cli
   

2. 生成文档：执行以下命令生成HTML格式文档（可替换为html2、markdown等格式）：

   openapi-generator-cli generate \
     -i ./path/to/openapi.yaml \  # 规范文件路径
     -l html2 \                   # 输出格式
     -o ./path/to/output/docs     # 输出目录
   

3. 集成到构建流程：将生成命令添加到项目的Makefile、pom.xml（Maven）或build.gradle（Gradle）中，实现“代码变更→自动生成文档”的自动化。例如，在Maven的pom.xml中添加exec-maven-plugin插件：

   <build>
       <plugins>
           <plugin>
               <groupId>org.codehaus.mojogroupId>
               <artifactId>exec-maven-pluginartifactId>
               <version>3.1.0version>
               <executions>
                   <execution>
                       <phase>generate-resourcesphase> 
                       <goals>
                           <goal>execgoal>
                       goals>
                       <configuration>
                           <executable>openapi-generator-cliexecutable>
                           <arguments>
                               <argument>generateargument>
                               <argument>-iargument>
                               <argument>${project.basedir}/src/main/resources/openapi.yamlargument>
                               <argument>-largument>
                               <argument>html2argument>
                               <argument>-oargument>
                               <argument>${project.build.directory}/generated-docsargument>
                           arguments>
                       configuration>
                   execution>
               executions>
           plugin>
       plugins>
   build>
   

   执行mvn generate-resources时，会自动调用OpenAPI Generator生成文档。

三、自动化触发方式

为实现“代码提交→自动生成文档”的全自动化，可结合Git钩子或CI/CD工具（如Jenkins、GitHub Actions）：

1. Git钩子（Pre-commit）：在.git/hooks/pre-commit中添加生成命令（如openapi-generator-cli generate），提交代码前自动执行。
2. CI/CD流水线：在Jenkins或GitHub Actions的构建步骤中添加文档生成命令，例如GitHub Actions的workflow配置：

   jobs:
     generate-docs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Set up JDK
           uses: actions/setup-java@v3
           with:
             java-version: '17'
             distribution: 'temurin'
         - name: Generate OpenAPI Docs
           run: |
             wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.6.0/openapi-generator-cli-6.6.0.jar -O openapi-generator-cli.jar
             java -jar openapi-generator-cli.jar generate -i src/main/resources/openapi.yaml -l html2 -o target/generated-docs
         - name: Upload Docs
           uses: actions/upload-artifact@v3
           with:
             name: swagger-docs
             path: target/generated-docs
   

   每次代码推送至GitHub时，自动触发文档生成并上传为构建产物。

四、注意事项

1. 规范文件准确性：确保swagger.yaml/openapi.json符合OpenAPI规范（如字段类型、路径格式），否则会导致生成失败。可使用Swagger Editor（swagger-editor-cli validate）验证规范文件。
2. 依赖兼容性：Springdoc需与Spring Boot版本兼容（如Spring Boot 3.x对应Springdoc 2.x），避免版本冲突。
3. 动态更新：若使用注解方式，修改代码中的注解后，需重启应用（或启用Spring Boot的spring.devtools.restart.enabled=true）才能看到最新文档；若使用规范文件方式，修改后重新生成即可。

以上就是关于“如何在Ubuntu上实现Swagger自动化生成”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！

简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm