如何为SpringDoc接口操作配置代理重写后的自定义路径？

针对你遇到的反向代理路径重写后，SpringDoc生成的文档路径与实际对外路径不符的问题，这里有两种实用的解决方案，你可以根据场景选择：

方案一：单个接口直接用@Operation指定路径 #

如果你只需要修改某一个接口的文档路径，最简单的方式就是直接在@Operation注解中添加path属性，覆盖@RequestMapping中的路径：

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DataController {

    @Operation(summary = "Expose some data", path = "/b")
    @RequestMapping(path = "/a", produces = MediaType.APPLICATION_JSON_VALUE, method = RequestMethod.GET)
    public ResponseEntity<MyDto> getData() {
        // 你的业务逻辑
        return ResponseEntity.ok(new MyDto());
    }
}

这样配置后，SpringDoc生成的OpenAPI文档中，这个接口的访问路径就会显示为/b，而不再使用@RequestMapping里的/a。这个方法适合单个或少量接口的路径修改，配置起来非常直接。

方案二：全局自定义路径（适合多接口或动态场景） #

如果你有多个接口需要修改路径，或者需要根据环境动态调整路径，可以通过OpenApiCustomiser来全局修改OpenAPI文档中的路径映射：

创建一个Spring配置类，实现自定义的路径替换逻辑：

import io.swagger.v3.oas.models.OpenAPI;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocCustomConfig {

    @Bean
    public OpenApiCustomiser pathRewriteCustomiser() {
        return openApi -> {
            // 遍历所有文档中的路径
            openApi.getPaths().forEach((originalPath, pathItem) -> {
                // 将原来的/a路径替换为/b
                if ("/a".equals(originalPath)) {
                    openApi.getPaths().remove(originalPath);
                    openApi.getPaths().addPathItem("/b", pathItem);
                }
            });
        };
    }
}

这个方法可以批量处理路径替换，甚至可以结合环境变量等动态生成目标路径，灵活性更高。

注意事项 #

• 确保你使用的SpringDoc版本支持@Operation的path属性（一般v1.6.0及以上版本都支持）。
• 如果使用方案二，注意不要误删或替换掉其他不需要修改的路径，建议添加明确的判断条件。

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