1. 程式人生 > >springfox-swagger-ui 在二級目錄下的路徑問題

springfox-swagger-ui 在二級目錄下的路徑問題

本文解決 springfox-swagger-ui 在二級目錄下的使用問題。如同一個域名的 /user 和 /post 用 Nginx 分別反向代理指向不同的應用,我們希望在每個應用中都可以正常使用 Swagger。

很多人愛折騰,總要找到個辦法,甚至很多人會打起修改原始碼的主意,希望本文能幫你節省點時間。

注意:本文使用的 springfox-swagger2 版本是 2.6.0

修改全域性 context path

Spring Boot 環境中只要配置以下環境變數即可:

server.contextPath=/user

那麼你的所有的介面,預設就都是在 /user 下面了,自然 swagger-ui 也就能正常使用了,訪問 /user/swagger-ui.html

 即可。

這是最最簡單的方法,不過在有些特定的環境中會有問題,比如我司:

由於設定了 contextPath,那麼健康檢測介面 /health 也會被自動換為 /user/health,而我們的釋出系統一根筋地要找 /health 介面,也就導致我們的應用會發布不了。

只有在碰到這種方法解決不了的時候,我們才要考慮使用下面介紹的方法。

使用 Controller 做 forward

首先,將 /user/swagger-ui.html forward 到 /swagger-ui.html

這樣 swagger-ui.html 頁面中,它的 basePath 會變為 www.javadoop.com/user

,然後將 swagger-ui.html 頁面中的所有呼叫相應 forward 即可。

@Controller
// 看這裡
@RequestMapping("user")
public class SwaggerController extends BaseController {

    @GetMapping("/swagger-ui.html")
    public String index() {
        return "forward:/swagger-ui.html";
    }

    @GetMapping("/webjars/springfox-swagger-ui/css/{s:.+}")
    public String css(@PathVariable String s) {
        return "forward:/webjars/springfox-swagger-ui/css/" + s;
    }

    @GetMapping("/webjars/springfox-swagger-ui/{s:.+}")
    public String baseJs(@PathVariable String s) {
        return "forward:/webjars/springfox-swagger-ui/" + s;
    }

    @GetMapping("/webjars/springfox-swagger-ui/lib/{s:.+}")
    public String js(@PathVariable String s) {
        return "forward:/webjars/springfox-swagger-ui/lib/" + s;
    }

    @GetMapping("/webjars/springfox-swagger-ui/images/{s:.+}")
    public String images(@PathVariable String s) {
        return "forward:/webjars/springfox-swagger-ui/images/" + s;
    }

    @GetMapping("/swagger-resources/configuration/ui")
    public String ui() {
        return "forward:/swagger-resources/configuration/ui";
    }

    @GetMapping("/swagger-resources")
    public String resources() {
        return "forward:/swagger-resources";
    }

    @GetMapping("/v2/api-docs")
    public String docs() {
        return "forward:/v2/api-docs";
    }

    @GetMapping("/swagger-resources/configuration/security")
    public String security() {
        return "forward:/swagger-resources/configuration/security";
    }
}

使用 ViewControllerRegistry

很多人會使用下面的方法來寫,我們也來看一下:

@Configuration
public class WebConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/user/**").addResourceLocations("classpath:/META-INF/resources/");
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("/user/v2/api-docs", "/v2/api-docs").setKeepQueryParams(true);
        registry.addRedirectViewController("/user/swagger-resources/configuration/ui","/swagger-resources/configuration/ui");
        registry.addRedirectViewController("/user/swagger-resources/configuration/security","/swagger-resources/configuration/security");
        registry.addRedirectViewController("/user/swagger-resources", "/swagger-resources");
    }
}

這種寫法,訪問靜態資源的時候是完全沒有問題的,但是 swagger-ui.html 在使用 ajax 呼叫介面的時候,這種配置做的是跳轉,如 "/user/v2/api-docs" 自動跳轉到 "/v2/api-docs" 其實是不滿足我們需求的。因為 /v2/api-docs 這個路徑根本就不會跳到我們的 user 應用。