Spring Boot 3+OpenAPI 3：如何配置从"/"重定向到/swagger-ui/index.html？

问题分析 #

• @RestController会将返回的字符串直接作为响应体返回，不会触发Spring的重定向视图逻辑，导致返回的redirect:...字符串无法生效。
• 该根路径的@GetMapping方法会被Swagger注解扫描到，因此会出现在OpenAPI文档中。

解决方案 #

1. 修复重定向逻辑 #

方式一：单独使用@Controller处理重定向

将根路径重定向方法放到独立的@Controller类中，避免影响其他REST接口：

@Controller
public class HomeRedirectController {    

    @GetMapping(value = "")
    public String index() {
        var baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
        return String.format("redirect:%s/swagger-ui/index.html", baseUrl);
    }
}

方式二：用ResponseEntity构建重定向响应（保留@RestController）

如果不想拆分控制器，可手动构建重定向响应：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import java.net.URI;

@RestController
public class Controller {    

    @GetMapping(value = "")
    public ResponseEntity<Void> index() {
        var baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
        String redirectUrl = String.format("%s/swagger-ui/index.html", baseUrl);
        return ResponseEntity.status(HttpStatus.FOUND).location(URI.create(redirectUrl)).build();
    }
    // other methods
}

2. 隐藏根路径端点 #

在重定向方法上添加Swagger的@Hidden注解，让Swagger扫描时忽略该端点：

import io.swagger.v3.oas.annotations.Hidden;

// 配合任意一种重定向方式使用
@GetMapping(value = "")
@Hidden
public String index() {
    // 重定向逻辑
}

额外优化（无需编写控制器方法） #

通过Spring Boot配置类注册重定向视图控制器，既实现重定向，又不会生成多余API端点：

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

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("", "/swagger-ui/index.html");
    }
}

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