单个OpenAPI Bean如何实现内外部API文档条件化配置

完全可以通过单OpenAPI基础Bean配合分组配置实现一次启动同时生成内部、外部两类API文档，无需切换配置两次启动应用。

核心实现思路 #

移除原有两个带条件装配的OpenAPI Bean，把两类文档共用的通用配置抽到单个基础OpenAPI Bean中，再通过SpringDoc提供的分组能力，分别为内部、外部文档定义独立分组，在分组维度配置所有差异化规则：

• 外部文档专属扩展项：在外部分组的自定义逻辑中追加专属扩展配置
• 不同访问服务地址：每个分组独立配置自己的Server信息
• 其他差异化配置（如接口扫描范围、文档描述信息、安全校验规则等）都可以在对应分组中独立设置

实现代码 #

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    /**
     * 两类文档共用的基础OpenAPI配置
     */
    @Bean
    public OpenAPI baseOpenApi() {
        return new OpenAPI()
                .openapi("3.0.0");
    }

    /**
     * 外部API文档分组配置
     */
    @Bean
    public GroupedOpenApi externalOpenApi() {
        return GroupedOpenApi.builder()
                .group("external-api")
                // 按实际外部接口的路径规则配置扫描范围
                .pathsToMatch("/api/external/**")
                .addOpenApiCustomizer(openApi -> {
                    // 配置外部文档专属服务地址
                    openApi.addServersItem(new Server()
                            .url("https://external-url")
                            .description("Development environment"));
                    // 在此处追加外部文档专属的扩展项配置
                    // 示例：openApi.addExtension("x-custom-ext", "外部文档专属扩展内容");
                })
                .build();
    }

    /**
     * 内部API文档分组配置
     */
    @Bean
    public GroupedOpenApi internalOpenApi(Info internalDocInfo) {
        return GroupedOpenApi.builder()
                .group("internal-api")
                // 按实际内部接口的路径规则配置扫描范围
                .pathsToMatch("/api/internal/**")
                .addOpenApiCustomizer(openApi -> {
                    // 配置内部文档专属服务地址
                    openApi.addServersItem(new Server()
                            .url("https://internal-url")
                            .description("Production environment"));
                    // 配置内部文档专属的说明信息
                    openApi.setInfo(internalDocInfo);
                })
                .build();
    }
}

使用说明 #

• 应用启动后，两类文档拥有独立的访问地址，无需重启即可分别获取：
  • 外部文档拉取地址：/v3/api-docs/external-api
  • 内部文档拉取地址：/v3/api-docs/internal-api
• 如果集成了Swagger UI，页面右上角会自动展示两个分组的切换入口，可直接在线预览两类文档
• 如果需要将文档导出到独立存储位置，直接调用上述两个地址拉取对应的JSON/YAML格式内容落盘即可，单次启动就能完成两类文档的全量生成，大幅降低文档生成耗时。

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