欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

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

程序员文章站 2022-05-03 18:29:31
...

前言

首先,把 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目录下,如下图所示

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

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;

    @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")注解,扫描指定的配置文件。

Step 5:添加资源的映射

@Configuration
public class InterceptorConfig extends WebMvcConfigurerAdapter {

    /**
     * Swagger 增加 url 映射
     *
     * @param registry 注册器
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/selfpath/swagger/**").addResourceLocations("classpath:/swagger/dist/");
    }
}

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

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

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

总结

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

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

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


参考资料