今天是新冠确诊的第二天，得了新冠也不要忘记学习啊！🥯

1.Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

---

2.在项目中使用Swagger

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X +使用的是PathPatternMatcher，所以我们还需要修改一下SpringBoot配置文件内容：

新增如下配置：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

配置swagger 编写一个configure类：

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

之后启动项目，访问如下地址，可以看到Swagger的初始化页面：

http://localhost:8080/swagger-ui/index.html#/

可以看到，我们编写的HelloController已经被Swagger扫描到了！

---

3.配置swagger

我们可以配置Swagger，实现基本页面的自定义：如下代码：

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
    // 配置了swagger的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置swagger信息 apiInfo
    private ApiInfo apiInfo() {
        Contact contact = new Contact("klza", "http://localhost:8080", "3390205563@qq.com");
        return new ApiInfo(
                "klza",
                "中国最大的网络安全服务商",
                "1.0",
                "imustctf.top",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

效果：

---

4.swagger配置扫描接口

swagger默认会扫描全部路径下的API信息，我们可以进一步细化它的扫描范围：

需要对docket方法稍作改动：

例如：我们只想扫描controller包：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.klza.controller"))
            .build();
}

此时重启项目，error的API接口就扫描不到了！

---

5.配置API文档的分组

修改Docket中的groupName属性即可，若要配置多个组，就需要多个Docket：

先看看如何分组：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("视频业务")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.klza.controller"))
            .build();
}

重启项目，看到了分组情况：

配置多个分组，开启多个Docket即可：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("视频业务")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.klza.controller"))
            .build();
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("军火库业务");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("竞赛业务");
}

---

6.swagger的实体类扫描

swagger很聪明，在controller中返回一个实体类对象，之后swagger就会在api中的model中生成一个实体类

例如：我们定义一个pojo类：

public class User {
    public String name;
    public String info;
}

在controller中使用它：

@GetMapping("/user")
public User user() {
    return new User();
}

重新启动项目，在model中会生成对应的实体类信息：

这还不够！我们还可以给实体类及其字段增加文档注释：

@ApiModel("用户实体类") // 给类加一个api注释
public class User {
    @ApiModelProperty("名字") // 给字段加一个api注释
    public String name;
    @ApiModelProperty("个人简介")
    public String info;
}

重启项目，看看效果：

---

7.给Controller加文档注释

给一个controller的方法加注释，使用@ApiOperation("xxx")：

@RestController
public class HelloController {
    @ApiOperation("Hello控制类")
    @GetMapping("/hello")
    public String hello() {
        return "hello";
    }

    @ApiOperation("获得一个user")
    @GetMapping("/user")
    public User user() {
        return new User();
    }
}

还可以给参数加文档注释：

public String hello(@ApiParam("用户名") String username){
    return "hello";
}