Swagger OpenAPI如何为不同包下的API分别配置独立Swagger UI

1. 确认依赖引入 #

首先确保你的项目已引入springdoc-openapi相关依赖（针对Spring Boot项目）：

• Maven依赖示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>最新稳定版</version>
</dependency>

• Gradle依赖示例：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:最新稳定版'

如果是WebFlux项目，请替换为springdoc-openapi-starter-webflux-ui依赖。

2. 配置分组OpenApi #

保留你现有的全局OpenAPI Bean，新增三个分组Bean，分别对应三类接口的包扫描规则和路径匹配规则：

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

@Configuration
class SwaggerConfig {

    // 你原有的全局公共配置，三个分组共用
    @Bean
    fun openApi(): OpenAPI = OpenAPI().info(Info().title("Test title"))

    // 对外api分组
    @Bean
    fun apiGroup(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("api")
            // 替换为你项目中controller.api包的完整路径
            .packagesToScan("com.yourproject.controller.api")
            .pathsToMatch("/api/**")
            .build()
    }

    // 管理后台api分组
    @Bean
    fun adminGroup(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("admin")
            .packagesToScan("com.yourproject.controller.admin")
            .pathsToMatch("/admin/**")
            .build()
    }

    // 内部服务api分组
    @Bean
    fun internalGroup(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("internal")
            .packagesToScan("com.yourproject.controller.internal")
            .pathsToMatch("/internal/**")
            .build()
    }
}

3. 配置访问路径转发 #

为了实现你要求的自定义访问路径，需要配置Spring MVC视图转发规则，让指定路径直接跳转到对应分组的Swagger UI：

import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer

@Configuration
class WebConfig : WebMvcConfigurer {
    override fun addViewControllers(registry: ViewControllerRegistry) {
        registry.addViewController("/api/swagger-ui.html")
            .setViewName("forward:/swagger-ui.html?group=api")
        registry.addViewController("/admin/swagger-ui.html")
            .setViewName("forward:/swagger-ui.html?group=admin")
        registry.addViewController("/internal/swagger-ui.html")
            .setViewName("forward:/swagger-ui.html?group=internal")
    }
}

4. 可选配置项 #

你可以在application.yml或application.properties中添加以下配置优化使用体验：

springdoc:
  swagger-ui:
    # 关闭默认的Swagger首页，直接跳转到对应分组
    disable-swagger-default-url: true
    # 展示接口请求耗时
    display-request-duration: true
  api-docs:
    enabled: true

访问验证 #

项目启动后直接访问以下路径即可查看对应分组的接口文档：

• 对外API文档：http://localhost:8080/api/swagger-ui.html
• 管理后台API文档：http://localhost:8080/admin/swagger-ui.html
• 内部服务API文档：http://localhost:8080/internal/swagger-ui.html

内容的提问来源于stack exchange，提问作者Вячеслав Чернышов