如何在GitLab流水线中从Spring Boot源码生成OpenAPI.yaml文件？

方案1：用SpringDoc OpenAPI Maven插件自动生成 #

如果你的项目基于SpringDoc（Spring官方推荐的OpenAPI实现），可以通过Maven插件完成启动应用、抓取规范、自动停止应用的全流程，无需手动操作，非常适合CI场景。

1. 在pom.xml中添加插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.4.0</version> <!-- 替换为最新稳定版本 -->
            <executions>
                <execution>
                    <id>export-openapi</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <phase>verify</phase> <!-- 绑定到verify阶段，构建时自动执行 -->
                </execution>
            </executions>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl> <!-- SpringDoc默认API文档地址，按需调整 -->
                <outputFileName>openapi.json</outputFileName> <!-- 支持生成.json或.yaml格式 -->
                <outputDir>${project.build.directory}/openapi</outputDir> <!-- 文件输出目录 -->
                <waitTimeInSeconds>2</waitTimeInSeconds> <!-- 等待应用启动的时间，按需调整 -->
            </configuration>
        </plugin>
    </plugins>
</build>

2. 在GitLab-CI的gitlab-ci.yml中配置执行流程：

stages:
  - generate-openapi
  - spectral-lint

generate-openapi:
  stage: generate-openapi
  image: maven:3.8.6-openjdk-17
  script:
    - mvn verify -DskipTests
  artifacts:
    paths:
      - target/openapi/openapi.json

spectral-lint:
  stage: spectral-lint
  image: stoplight/spectral:latest
  script:
    - spectral lint target/openapi/openapi.json

方案2：通过Spring Boot启动参数直接导出规范 #

如果不想用插件，可通过自定义组件让应用启动后自动生成规范文件并退出，无需手动调用wget：

1. 在项目中添加CommandLineRunner组件（依赖SpringDoc）：

import org.springdoc.api.OpenApiResource;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;

@Component
public class OpenApiExporter implements CommandLineRunner {

    private final OpenApiResource openApiResource;
    private final ObjectMapper objectMapper;

    public OpenApiExporter(OpenApiResource openApiResource, ObjectMapper objectMapper) {
        this.openApiResource = openApiResource;
        this.objectMapper = objectMapper;
    }

    @Override
    public void run(String... args) throws Exception {
        // 生成OpenAPI对象并写入文件
        var openApi = openApiResource.openapi();
        objectMapper.writerWithDefaultPrettyPrinter()
                    .writeValue(new File("target/openapi.json"), openApi);
        // 写入完成后立即退出应用
        System.exit(0);
    }
}

2. 在CI中执行启动命令生成文件：

mvn spring-boot:run -Dspring-boot.run.arguments="--spring.main.close-context-on-start=true"

执行后应用会自动启动、生成文件并退出，直接用生成的target/openapi.json做Spectral校验即可。

方案3：Gradle项目适用的SpringDoc插件 #

如果项目用Gradle，可通过对应插件完成自动生成：

1. 在build.gradle中添加插件和配置：

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'org.springdoc.openapi-gradle-plugin' version '1.8.0'
}

openApi {
    apiDocsUrl = "http://localhost:8080/v3/api-docs"
    outputFileName = "openapi.yaml"
    outputDir = file("${buildDir}/openapi")
    waitTimeInSeconds = 2
}

2. 在CI中执行Gradle命令：

./gradlew generateOpenApi

生成的文件会放在build/openapi/目录下，直接用于Spectral校验即可。

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