Spring Boot 自定义 Swagger2 请求 URL 路径的两种方法

前言

首先,把 Swagger2 的依赖引进来:

<!--swagger 版本-->
<swagger.version>2.7.0</swagger.version>

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

然后,建立 Swagger2 的配置文件:

@EnableSwagger2
@Configuration
@Profile({"qa", "rd", "beta"})
public class Swagger2Config extends WebMvcConfigurerAdapter {

    @Value("${swagger.enable:false}")
    private boolean enableSwagger;

    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hit.math.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("Swagger2-接口文档")
                .version("v1.0.0")
                .build();
    }
}

默认情况下,Swagger2 的访问路径为:

  • http://localhost:端口/swagger-ui.html

如果我们想要修改上述的请求路径,则需要进行一些修改。

在这里,以 Spring Boot 项目为例,给出两种自定义 Swagger2 请求 URL 路径的方法。

方法一:修改应用根路径

对于第一种方法,非常简单,我们只需要在application.yml文件中,新增以下配置即可:

server:
  port: 8215
  tomcat:
    basedir: /tmp/tomcat
  servlet: # 添加统一服务前缀
    context-path: /selfpath

如上述配置所示,其中/selfpath就是我们修改的应用根路径,也是我们自定义的请求路径。

新增上述配置之后,再想访问 Swagger2,地址就应该是:

  • http://localhost:端口/selfpath/swagger-ui.html

方法二:引入 Swagger2 前端代码

对于第二种方法,说实话,不太好,但在某些限制我们修改应用根路径的情况下,也能解决我们的问题。

具体的操作步骤,如下:

Step 1:访问swagger-ui代码仓库,选择一个 2.0 以上、3.0 以下的版本,将其中的dist文件夹拷贝到我们自己项目中的resources/swagger目录下,如下图所示

swagger-ui-dist

Step 2:在resources下新建swagger.properties文件,其中的内容为

springfox.documentation.swagger.v2.path=/selfpath/swagger

Step 3:修改dist目录下面的index.html页面,文件内搜索以下内容

url = "http://petstore.swagger.io/v2/swagger.json";

将其替换为

url = "/selfpath/swagger";

替换后,该部分的代码大致为

	  ......
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
//        url = "http://petstore.swagger.io/v2/swagger.json";
        url = "/selfpath/swagger";
      }

      hljs.configure({
        highlightSizeThreshold: 5000
      });

      // Pre load translate...
      if(window.SwaggerTranslator) {
        window.SwaggerTranslator.translate();
      }
	  ......

Step 4:修改Swagger2Config配置文件,并添加资源的映射

@EnableSwagger2
@Configuration
@Profile({"qa", "rd", "beta"})
@PropertySource("classpath:swagger.properties")
public class Swagger2Config extends WebMvcConfigurerAdapter {

    @Value("${swagger.enable:false}")
    private boolean enableSwagger;

	/**
     * Swagger 增加 url 映射
     *
     * @param registry 注册器
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/selfpath/swagger/**").addResourceLocations("classpath:/swagger/dist/");
    }
    
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hit.math.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("Swagger2-接口文档")
                .version("v1.0.0")
                .build();
    }
}

与开篇处的配置文件相比,新增了@PropertySource("classpath:swagger.properties")注解,扫描指定的配置文件。

按上述的步骤操作完之后,剩下的就是进行验证了。但与第一种方法不同,使用第二种方法配置完之后,Swagger2 的访问路径应该为:

  • http://localhost:端口/selfpath/swagger/index.html

其中,我们自定义的路径为/selfpath,在实际使用的时候,可以根据需要进行替换。

总结

对于本文所述的两种方法,博主都在实际的项目中使用过。最后,简单总结一下:

  • 推荐第一种方法,修改应用根路径,简单易用,而且不影响我们后续升级 Swagger2 的版本;
  • 不推荐第二种方法,引入 Swagger2 前端代码,对我们的项目侵入性太大,而且影响我们后续升级 Swagger2 的版本。

特别地,在swagger-ui的 3.0 版本之后,该项目调整了目录结构,已经没有dist目录了。


参考资料

已标记关键词 清除标记
相关推荐
©️2020 CSDN 皮肤主题: 代码科技 设计师:Amelia_0503 返回首页
实付 9.90元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值