如何无需运行Spring应用生成OpenAPI规范？适配GitHub Action场景

当然有办法不用启动Spring Boot应用就能生成OpenAPI规范，下面是两种可靠的实现方式，完全适配GitHub Action的自动化流程：

1. 直接使用springdoc-openapi-maven-plugin的离线生成目标 #

springdoc-openapi-maven-plugin本身支持离线扫描类文件生成规范，不需要启动Spring上下文。你只需要在pom.xml里配置插件的generate目标，指定要扫描的包路径和主类即可：

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.2.0</version> <!-- 建议使用最新稳定版，适配你的Spring Boot版本 -->
    <executions>
        <execution>
            <id>generate-openapi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <apiDocsUrl>http://placeholder</apiDocsUrl> <!-- 离线模式下随便填，不会实际调用 -->
                <packagesToScan>com.your.project.controller</packagesToScan> <!-- 替换成你的Controller所在包 -->
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}/openapi</outputDir>
                <springBootApplicationClass>com.your.project.YourSpringBootApplication</springBootApplicationClass> <!-- 项目主类全路径 -->
            </configuration>
        </execution>
    </executions>
</plugin>

配置完成后，直接执行以下Maven命令就能生成规范：

mvn springdoc-openapi:generate

这个命令会直接扫描编译后的类文件，解析所有OpenAPI相关注解（@RestController、@Operation、@Parameter等），生成符合要求的规范文件，全程不需要启动应用。

2. 绑定到构建阶段自动生成 #

如果想让规范生成和项目构建流程绑定，比如执行mvn package时自动生成，可以把插件绑定到process-classes阶段：

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.2.0</version>
    <executions>
        <execution>
            <phase>process-classes</phase> <!-- 编译完成后自动执行生成 -->
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <packagesToScan>com.your.project.controller</packagesToScan>
                <outputDir>${project.build.directory}/openapi</outputDir>
                <springBootApplicationClass>com.your.project.YourSpringBootApplication</springBootApplicationClass>
            </configuration>
        </execution>
    </executions>
</plugin>

这样每次构建项目时，规范文件会自动生成到指定目录，不需要单独执行命令。

GitHub Action中的实现示例 #

创建.github/workflows/generate-openapi.yml文件，实现自动化生成并上传规范文件：

name: Generate OpenAPI Specification
on: [push, pull_request]

jobs:
  build-and-generate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Java environment
        uses: actions/setup-java@v4
        with:
          java-version: '17' # 替换成你的项目使用的Java版本
          distribution: 'temurin'
          cache: maven # 缓存Maven依赖，加快构建速度

      - name: Compile code and generate OpenAPI spec
        run: mvn springdoc-openapi:generate

      - name: Upload OpenAPI spec as artifact
        uses: actions/upload-artifact@v4
        with:
          name: openapi-specification
          path: target/openapi/openapi.json # 对应插件配置的输出路径

执行这个Action时，会自动完成代码检出、Java环境配置、生成规范，并把生成的文件作为构建产物上传，后续可以直接下载使用。

注意事项 #

• 确保插件版本和你的Spring Boot版本兼容：Spring Boot 3.x需要使用springdoc-openapi-maven-plugin 1.x及以上版本；Spring Boot 2.x对应0.x版本。
• packagesToScan要包含所有带有OpenAPI注解的类所在的包，避免遗漏接口。
• 如果项目中有自定义的OpenAPI配置类（比如用@OpenAPIDefinition定义全局信息），插件会自动扫描并应用这些配置，不需要额外处理。

内容的提问来源于stack exchange，提问作者Lukas