无需运行Spring Boot应用生成OpenAPI Spec及相关方案咨询

1. 无需运行Spring Boot应用生成Spec的方法 #

springdoc-openapi-gradle-plugin确实依赖启动应用来生成文档，但有两种可行的替代方案：

• 使用Swagger Core官方Gradle插件：io.swagger.core.v3.swagger-gradle-plugin 支持通过扫描代码中的OpenAPI注解（如@Operation、@ApiResponse、@Parameter等）直接生成OpenAPI 3.x Spec，完全不需要启动Spring Boot应用。在build.gradle中配置插件后，只需指定要扫描的包路径、输出文件路径和格式（JSON/YAML）即可执行生成任务。
• 自定义Gradle任务手动构建Spec：利用springdoc-openapi-core提供的OpenAPIBuilder API，编写Groovy/Kotlin代码手动定义API元数据、接口路径、响应模型等，适合需要高度定制文档结构的场景。这种方式无需依赖Spring上下文，但需要手动维护API定义，不如插件自动扫描高效。

2. 每次运行Spring Boot应用时自动生成Spec #

通过Gradle的任务依赖机制即可实现：
在build.gradle中添加如下配置，让bootRun任务依赖generateOpenApiDocs任务，这样每次执行./gradlew bootRun时，会先自动运行文档生成任务，再启动应用：

bootRun.dependsOn(generateOpenApiDocs)

注意：springdoc插件的generateOpenApiDocs默认会启动一个forked的Spring Boot进程生成文档，生成完成后会自动关闭，不会与后续bootRun启动的进程冲突。

3. 将Spec生成纳入集成测试 #

可行，且推荐在集成测试阶段利用已启动的应用来生成更准确的Spec：

• 方案一：在集成测试代码中获取并保存Spec
  利用Spring WebFlux的WebTestClient，在集成测试中添加一个专门的测试方法，调用springdoc默认的/v3/api-docs接口获取Spec内容，然后写入到指定文件。示例代码（Kotlin）：

  @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
  class OpenApiDocIntegrationTest {
      @Autowired
      lateinit var webTestClient: WebTestClient
  
      @Test
      fun generateOpenApiSpec() {
          val specContent = webTestClient.get()
              .uri("/v3/api-docs")
              .exchange()
              .expectStatus().isOk
              .expectBody(String::class.java)
              .returnResult()
              .responseBody
  
          Files.write(Paths.get("build/docs/openapi.json"), specContent!!.toByteArray())
      }
  }
  

  确保这个测试在集成测试阶段执行，即可在应用运行时生成并保存Spec。
• 方案二：通过Gradle任务依赖绑定
  让集成测试任务（如integrationTest）依赖generateOpenApiDocs，但这种方式会让插件单独启动一次应用生成文档，再启动应用执行集成测试，存在重复启动的开销，不如方案一高效。

适合Spring WebFlux的替代插件推荐 #

• Swagger Core Gradle插件：如前文所述，支持无启动生成Spec，完全兼容Spring WebFlux的注解写法。
• Spring REST Docs + OpenAPI扩展：通过编写WebTestClient测试用例生成文档片段，再结合org.springframework.restdocs:spring-restdocs-openapi扩展生成OpenAPI Spec。这种方式需要编写测试用例，但能保证文档与实际接口行为一致，且仅需加载Spring测试上下文，无需启动完整服务器。

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