如何更改 Springfox Swagger 2.0 的 basePath

Posted 2023-02-16

【中文标题】如何更改 Springfox Swagger 2.0 的 basePath

【英文标题】：How to change basePath for Springfox Swagger 2.0

【发布时间】：2016-07-11 23:07:06

【问题描述】：

我正在运行一项服务，可通过以下方式访问 Swagger UI：

http://serviceURL/swagger-ui.html

但是，它是在代理后面，例如：

http://proxyURL/serviceName

Swagger UI 生成的 URL 如下所示：

http://proxyURL/

而不是以 serviceName 作为后缀的实际 URL。 据我所知，这意味着操纵 basePath 属性。根据文档：

Swagger API 文档无法再描述对 不同的基本路径。在 1.2 和更早的版本中，每个资源都可以拥有 一个单独的基本路径。在 2.0 中，basePath 等效项 (schemes+host+basePath) 是为整个规范定义的。

@Api(basePath) 已弃用，并且没有说明使用什么以及如何使用它。如何让 Swagger 生成的路径正确显示？

我正在使用 Spring Boot、Springfox Swagger 和注释。

【问题讨论】：

你能解决这个@Martin 吗？

我刚刚做了 Docket.pathMapping("serviceName")，但我认为这只是 Springfox 中缺少功能的原始解决方法，仍在等待答案

我正在寻找同样的东西..

你设法解决了@MartinAsenov 这个问题吗？

【参考方案1】：

@Bean
public Docket newsApi(ServletContext servletContext) 
    return new Docket(DocumentationType.SWAGGER_2).pathProvider(new RelativePathProvider(servletContext) 
        @Override
        public String getApplicationBasePath() 
            return "/serviceName" + super.getApplicationBasePath();
        
    ).host("proxyURL");

【参考方案2】：

使用spring fox 2.9.2，使用其他用户提到的解决方案无效。

什么不工作：

覆盖 Docket pathProvider 上的 getApplicationBasePath 添加 server.servlet.context-path=/serviceName

我不知道为什么它们不起作用，但是在我使用 Springboot 2.1.6.RELEASE 和 Spring 5.1.8.RELEASE 的项目中，上面的两个解决方案被忽略了。

所以，我正在尝试另一种方法：https://github.com/springfox/springfox/issues/2817#issuecomment-517753110

根据 github 问题评论，我需要重写 Springfox json 序列化类，感谢上帝这有效。 下面是代码示例：

import io.swagger.models.Swagger;
import org.springframework.context.annotation.Primary;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;
import springfox.documentation.spring.web.json.JacksonModuleRegistrar;
import springfox.documentation.spring.web.json.Json;
import springfox.documentation.spring.web.json.JsonSerializer;

import java.util.Arrays;
import java.util.List;

import static io.github.jhipster.config.JHipsterConstants.SPRING_PROFILE_PRODUCTION;

@Component
@Primary
public class CustomBasePathSerialize extends JsonSerializer 

    // this injection is optional, if you don't need to
    // add basePath based on active profile, remove this.
    private final Environment env;

    public CustomBasePathSerialize(List<JacksonModuleRegistrar> modules,
                                   Environment env) 
        super(modules);
        this.env = env;
    

    @Override
    public Json toJson(Object toSerialize) 
        if (toSerialize instanceof Swagger) 
            Swagger swagger = (Swagger) toSerialize;
            String basePath = "/serviceName";
            List<String> profiles = Arrays.asList(env.getActiveProfiles());

            // OPTIONAL: you can change basePath if you have difference path 
            // on any Spring profile, for example prod:
            if (profiles.contains(SPRING_PROFILE_PRODUCTION)) 
                basePath = "/";
            
            swagger.basePath(basePath);
        
        return super.toJson(toSerialize);
    

【讨论】：

不幸的是，这仅适用于 Swagger 2，但仍然有效

【参考方案3】：

您可以像这样编辑您的 SwaggerConfiguration：

注意更换package（必须是 包含您的 REST 控制器）、host 和您需要的 PATH

@Configuration
@EnableSwagger2
public class SwaggerConfiguration implements WebMvcConfigurer 

    public static final String PATH = "/serviceName";

    @Bean
    public Docket api() 
        final var package = "com.martin.rest";
        final var host = "localhost:8080";

        return new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .select()
                .apis(RequestHandlerSelectors.basePackage(package))
                .paths(PathSelectors.any())
                .build();
    

    @Override
    public void addViewControllers(ViewControllerRegistry registry) 
        final var apiDocs = "/v2/api-docs";
        final var configUi = "/swagger-resources/configuration/ui";
        final var configSecurity = "/swagger-resources/configuration/security";
        final var resources = "/swagger-resources";

        registry.addRedirectViewController(PATH + apiDocs, apiDocs).setKeepQueryParams(true);
        registry.addRedirectViewController(PATH + resources, resources);
        registry.addRedirectViewController(PATH + configUi, configUi);
        registry.addRedirectViewController(PATH + configSecurity, configSecurity);
        registry.addRedirectViewController(PATH, "/");
    

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

另一种解决方案是更改 spring-boot URL context-path：

编辑倒application.properties文件：

server.servlet.context-path=/serviceName

或者如果你有一个application.yml 文件：

server:
  servlet:
    context-path: /serviceName

警告：它会改变你所有网络服务的基本路径，不仅仅是 Swagger