Quarkus OpenAPI扩展：如何在构建阶段获取生成的OpenAPI YAML文件

Quarkus SmallRye OpenAPI扩展原生支持构建阶段直接生成OpenAPI规格文件，全程不需要启动应用服务，生成的YAML内容和启动后访问/q/openapi端点拿到的结果完全一致，完全适配CI流程中给客户端代码生成器当输入的需求。

具体落地方式 #

临时单次生成 #

只要项目已经正常引入quarkus-smallrye-openapi扩展，直接在编译命令里加参数就能触发生成，不需要启服务：

• Maven项目执行：
  ./mvnw compile -Dquarkus.openapi.generate.files=true
• Gradle项目执行：
  ./gradlew compileJava -Dquarkus.openapi.generate.files=true
  生成的默认路径：Maven环境下在target/generated/openapi/目录，Gradle环境下在build/generated/openapi/目录，直接就能拿到完整的openapi.yaml文件。

适配CI流程的固化配置 #

如果不想每次构建都手动加参数，直接把生成逻辑写进项目配置，让常规构建动作自动产出文件就行，在application.properties里加对应配置：

# 开启构建期自动生成OpenAPI文件
quarkus.openapi.generate.files=true
# 自定义输出路径，方便CI脚本直接定位（可选）
quarkus.openapi.output.directory=./ci/openapi

配完之后，不管是本地跑mvn package还是CI流程里的常规构建步骤，都会在编译环节直接把YAML文件生成到指定路径，完全不需要穿插启动服务拉取文件的冗余步骤。

注意事项 #

• 构建期生成的规格和运行时端点返回的内容没有差异，背后走的是同一套注解扫描、配置合并、自定义定制逻辑的链路，不会出现内容不一致的问题。
• 整个生成过程是离线编译阶段的处理逻辑，不会启动服务端口、不会触发应用上下文的服务监听，不会出现CI环境下端口占用、启动超时这类常见问题，生成速度比启服务拉取快很多。
• 如果项目里有自定义的OpenAPI规格修改逻辑（比如拦截器动态调整参数、引用外部规格片段），这类逻辑在构建期生成时会正常执行，不需要额外改造。

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