如何验证springdoc生成的OpenAPI规范？含GitLab作业设想

1. 先导出规范文件再验证 #

springdoc支持在应用启动时自动把生成的OpenAPI规范导出到本地文件，不用再纠结运行时路径。只需在application.properties里加几行配置：

springdoc.api-docs.path=/v3/api-docs
springdoc.api-docs.output-dir=./openapi
springdoc.api-docs.output-format=yaml

启动应用后，项目根目录的openapi文件夹里会生成openapi.yaml文件。之后可以用两种方式验证：

• 用openapi-generator的openApiValidate任务，直接指定这个文件路径
• 用轻量工具swagger-cli，执行命令：

swagger-cli validate ./openapi/openapi.yaml

2. 直接请求API端点验证 #

不想导出文件的话，可以在验证时直接请求运行中应用的/v3/api-docs端点，拿到规范内容后传给验证工具。比如用curl结合swagger-cli：

curl http://localhost:8080/v3/api-docs | swagger-cli validate -

只要应用能正常启动，就能完成验证，省去文件导出步骤。

3. 集成到Spring Boot单元测试里 #

用org.openapi4j:openapi-validator这个库，在单元测试里直接获取springdoc生成的OpenAPI对象并验证。Kotlin示例代码：

import org.junit.jupiter.api.Test
import org.openapi4j.core.validation.ValidationException
import org.openapi4j.parser.OpenApiParser
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.web.context.WebApplicationContext

@SpringBootTest
class OpenApiValidationTest {

    @Autowired
    private lateinit var webApplicationContext: WebApplicationContext

    @Test
    fun validateOpenApiSpec() {
        val openApi = webApplicationContext.getBean(org.openapi4j.parser.model.v3.OpenApi3::class.java)
        val validationErrors = OpenApiParser.instance().validate(openApi, true)
        if (validationErrors.isNotEmpty()) {
            throw ValidationException("OpenAPI规范验证不通过: ${validationErrors.joinToString(", ")}")
        }
    }
}

把这段测试代码加到项目里，跑单元测试时就会自动验证规范，不用额外配置任务。

GitLab作业实现 #

方案1：基于导出文件的验证 #

open-api-validation:
  stage: test
  image: openjdk:17-alpine
  before_script:
    # 安装依赖工具
    - apk add --no-cache nodejs npm
    - npm install -g swagger-cli
    # 启动应用并导出规范
    - java -jar build/libs/your-app.jar &
    - sleep 10 # 等待应用启动完成
    - curl http://localhost:8080/v3/api-docs -o openapi.yaml
  script:
    - swagger-cli validate openapi.yaml
  after_script:
    # 清理应用进程
    - pkill -f your-app.jar

方案2：基于单元测试的验证 #

open-api-validation:
  stage: test
  image: openjdk:17-alpine
  script:
    - ./gradlew test --tests "*OpenApiValidationTest"

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