2021-11（java-springboot学习笔记五swagger）

swagger

使用swagger

配置swagger

配置swagger开关

动态配置项目环境，显示与不显示swagger

swagger

了解swagger概念作用
了解前后端分离
在springboot集成swagger

Swagger

号称最流行的api框架
Restful api文档
直接运行
支持多种语言

使用swagger

1.导入依赖

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2.编写hello，测试运行

3.编写一个配置类

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

4.访问 http://localhost:8080/swagger-ui.html

配置swagger

swagger实例bean是Docket

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}

@Configuration
@EnableSwagger2   //开启
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())    //关联ApiInfo 
                .select()
//               扫描指定包basePackage
                //any()全部
                //none():不扫描
                //withClassAnnotation()  扫描类上的注解
                .apis(RequestHandlerSelectors.basePackage("com.kun.springboot07swagger.controller"))
                 // 配置如何通过path过滤,即这里只扫描请求以/ss开头的接口
                .paths(PathSelectors.ant("/ss/**"))
                .build();
    }

配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("带鱼", "http://xiaocao.3vfree.cn/", "[email protected]");
        return new ApiInfo(
                "带鱼的api文档",
                "描述描述",
                "v1.0",
                "http://xiaocao.3vfree.cn/",
                contact,
                "Apache 2.0",
                "http://www.baidu.com",
                new ArrayList()
        );
    }
}

配置swagger开关

.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问

动态配置项目环境，显示与不显示swagger

@Bean
public Docket docket(Environment environment) {
   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b)
      .groupName("daiyu") // 配置分组
      .select()
      .build();
}

实体配置

1.新建一个实体类

//@Api("注释")
@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

2.只要是这个实体类在请求接口的返回值上，都能映射到实体项中

@Api(tags = "你好")
@RestController
public class HelloController {

    //   /error默认错误请求
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }
}

常用注解

swagger扩展

默认皮肤： 访问 http://localhost:8080/swagger-ui.html

<dependency> 
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

皮肤：访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

错误：

错误一：Failed to start bean 'documentationPluginsBootstrapper';

发现是SpringBoot的版本跟我Swagger的版本有冲突。

我SpringBoot用的2.6.1的版本，Swagger用的2.9.2的版本；最后降低了SpringBoot的版本为2.5.6解决了问题。

错误