springboot整合swagger3和swagger-ui-layer

1.引入jar包

<!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <!--swagger換皮膚-->
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>
           

2.在啟動類上添加注解 并編寫配置類

@EnableOpenApi

Swagger3Config.java

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author lzj
 * @date 2021/8/27
 */
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("包路徑.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder() .title("标題名")
                .description("描述")
                .contact(new Contact("作者名", "", ""))
                .version("1.0")
                .build();
    }
}

           

3.使用注解寫文檔

controller中的

加在類上的描述資訊

加在方法上的描述資訊

// 生成方法的含義
    @ApiOperation(value = "", notes = "")
    //參數的含義
    @ApiImplicitParam(name = "id",value = "使用者的id",paramType = "",dataType = "Integer")
    //傳回值的含義
    @ApiResponse(code = 200,message = "成功")
           

實體類上

可以對實體類進行相關描述

@ApiModel("使用者表")
public class User {
    /**
     * 使用者id
     */
    @ApiModelProperty(value = "使用者id")
    private Integer id;
}
           

4.通路位址

swagger3的通路位址：127.0.0.1:8080/swagger-ui/index.html

swagger-ui-layer通路位址： 127.0.0.1:8080/docs.html

5.注意總結

5.1 swagger3的位址和其他的不一樣，網上好多以前的位址，建議檢視官網指定版本

5.2 docs.html無法通路的問題

如果我們修改了springboot項目的靜态路徑的位置，會出現通路404的問題

mvc:
    static-path-pattern: /static/**
           

我這裡将靜态路徑通路的位置改成了static,我通路docs.html就404了

通路static/docs.html就一直轉圈 ， 無法擷取 /static/v2/api-docs的資料

是以想要使用這個換皮膚的swagger不能更改那個靜态資源路徑

但是我要通路static下的檔案通過 /static/xxx.js 之類的

因為我內建了shiro需要全部放行靜态資源 /static/**下的所有路徑

而預設springboot是将static下的檔案直接放到根路徑下可以通路

是以我就無法通過static/xxx.js通路，springboot會轉換成/xxx.js

然後就被攔住了

解決方法

1 .上面的配置，但是無法使用swagger-ui-layer了

2.配置一個資源路徑映射就可以了

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //将所有/static/** 通路都映射到classpath:/static/ 目錄下
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
    }