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

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

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

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

安装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+，维护更活跃），通过注解自动生成文档。

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

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- 使用最新稳定版 -->
</dependency>

（若使用Gradle，在build.gradle中添加：implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'）。

配置注解：在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<List<User>> 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));
    }
}

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

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

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

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

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

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

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

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

<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>exec-maven-plugin</artifactId>
            <version>3.1.0</version>
            <executions>
                <execution>
                    <phase>generate-resources</phase> <!-- 构建阶段：生成资源前 -->
                    <goals>
                        <goal>exec</goal>
                    </goals>
                    <configuration>
                        <executable>openapi-generator-cli</executable>
                        <arguments>
                            <argument>generate</argument>
                            <argument>-i</argument>
                            <argument>${project.basedir}/src/main/resources/openapi.yaml</argument>
                            <argument>-l</argument>
                            <argument>html2</argument>
                            <argument>-o</argument>
                            <argument>${project.build.directory}/generated-docs</argument>
                        </arguments>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

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

三、自动化触发方式

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

Git钩子（Pre-commit）：在.git/hooks/pre-commit中添加生成命令（如openapi-generator-cli generate），提交代码前自动执行。

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时，自动触发文档生成并上传为构建产物。

四、注意事项

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

0 赞

0 踩