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

CG国斌

发布于 2021-12-07 17:49:53

9.9K0

发布于 2021-12-07 17:49:53

文章被收录于专栏：维C果糖维C果糖

文章目录

前言

首先，把 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 前端代码

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

具体的操作步骤，如下：

GitHub: swagger-ui

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

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 的访问路径应该为：