springdoc-openapi-maven-plugin生成时机：运行时/构建时？SpringBoot运行时生成OpenAPI文档求方案

核心方案：使用springdoc-openapi-starter（WebMVC/WebFlux） #

要实现Spring Boot运行时生成并暴露OpenAPI文档，无需依赖maven插件，直接用springdoc的starter即可让应用启动后自动生成并对外提供JSON/YAML格式的文档。

步骤1：添加依赖 #

根据你的Spring Boot版本选择对应starter（Spring Boot 3.x搭配springdoc v2.x，Spring Boot 2.x搭配springdoc v1.x），在pom.xml中引入：

<!-- WebMVC项目 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

<!-- WebFlux项目替换为 -->
<!-- <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.2.0</version>
</dependency> -->

步骤2：启动应用后直接访问文档端点 #

应用启动成功后，通过以下URL获取文档：

• JSON格式：http://localhost:8080/v3/api-docs
• YAML格式：http://localhost:8080/v3/api-docs.yaml

步骤3：自定义文档信息（可选） #

如果需要设置文档标题、版本、描述等元信息，可以通过配置类或application.properties实现：

配置类方式

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户管理API")
                        .version("v1.0")
                        .description("提供用户增删改查及权限管理接口"));
    }
}

配置文件方式

springdoc.api-docs.title=用户管理API
springdoc.api-docs.version=v1.0
springdoc.api-docs.description=提供用户增删改查及权限管理接口

关于springdoc-openapi-maven-plugin的澄清 #

你遇到的文档差异是因为这个插件的本质是在构建阶段临时启动应用，抓取运行时生成的OpenAPI文档并保存到本地文件，并非直接静态生成文档。它的作用是在CI/CD流程中自动导出文档文件，而非让应用在运行时对外提供文档。如果你的需求是让应用运行时暴露文档端点，完全不需要这个插件。

额外场景：运行时主动导出文档到本地文件 #

如果需要在应用运行时手动触发文档导出到本地，可以编写一个简单接口，利用springdoc提供的OpenAPI Bean生成并写入文件：

@RestController
@RequestMapping("/api/tools")
public class DocsExportController {

    private final OpenAPI openAPI;
    private final ObjectMapper objectMapper;
    private final YamlMapper yamlMapper;

    public DocsExportController(OpenAPI openAPI, ObjectMapper objectMapper, YamlMapper yamlMapper) {
        this.openAPI = openAPI;
        this.objectMapper = objectMapper;
        this.yamlMapper = yamlMapper;
    }

    @GetMapping("/export/openapi/json")
    public ResponseEntity<String> exportJson() throws IOException {
        String jsonContent = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(openAPI);
        Files.write(Paths.get("openapi.json"), jsonContent.getBytes(StandardCharsets.UTF_8));
        return ResponseEntity.ok("JSON文档已导出到当前目录openapi.json");
    }

    @GetMapping("/export/openapi/yaml")
    public ResponseEntity<String> exportYaml() throws IOException {
        String yamlContent = yamlMapper.writeValueAsString(openAPI);
        Files.write(Paths.get("openapi.yaml"), yamlContent.getBytes(StandardCharsets.UTF_8));
        return ResponseEntity.ok("YAML文档已导出到当前目录openapi.yaml");
    }
}

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