第08课： 用swagger为SpringBoot生成接口文档

一、本课程目标：

1. 弄清楚，为什么要用swagger，它解决了什么问题？
2. 编码实现2个springboot接口，让swagger自动生成接口文档

二、为什么要用swagger,它解决了什么问题？

随着sprnigboot、springcloud等微服务的流行，在微服务的设计下，小公司微服务小的几十，大公司大的几百上万的微服务。这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档。在微服务的盛行下，成千上万的接口文档编写，不可能靠人力来编写，故swagger就产生了，它采用自动化实现并解决了人力编写接口文档的问题；它通过在接口及实体上添加几个注解的方式就能在项目启动后自动化生成接口文档，

Swagger 提供了一个全新的维护 API 文档的方式，有4大优点：

1. 自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2. 跨语言性，支持 40 多种语言。
3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
4. 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

三、把springboot的接口，自动生成接口文档

步骤一：pom文件引入依赖包

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

步骤二：修改配置文件

1.application.properties加入以下配置

#表示是否开启 Swagger，一般线上环境是关闭的
spring.swagger2.enabled=true

2.增加swagger的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value(value = "${spring.swagger2.enabled}")
    private Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.agan.bt"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("阿甘讲解 Spring Boot")
                .termsOfServiceUrl("https://study.163.com/provider/1016671292/index.htm")
                .version("1.0")
                .build();
    }
}

步骤三：在Controller里边定义API的相关的注解

在学习把springboot生成接口之前，我们有必要学习下swagger的常用注解：

以下2个接口，分别是GET、POST请求来做案例讲解。

@Api(description = "用户接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("修改某条数据")
    @GetMapping(value = "/u/{id}")
    public UserVO findById(@PathVariable  int id){
            Random rand = new Random();
            UserVO user=new UserVO();
            user.setId(id);
            String temp="temp01";
            user.setUsername(temp);
            user.setPassword(temp);
            int n = rand.nextInt(2);
            user.setSex((byte)n);
            return user;
    }

    @ApiOperation("单个用户查询，按userid查用户信息")
    @PostMapping(value = "/user/create", produces = APPLICATION_JSON_UTF8_VALUE, consumes = APPLICATION_JSON_UTF8_VALUE)
    public UserVO crreteUser(@RequestBody  UserVO userVO) {
        return userVO;
    }

}

@ApiModel(value = "用户信息")
@Data
public class UserVO {
    @ApiModelProperty(value = "用户ID")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "性别 0=女 1=男 ")
    private Byte sex;

    @ApiModelProperty(value = "删除标志，默认0不删除，1删除")
    private Byte deleted;

    @ApiModelProperty(value = "更新时间")
    private Date updateTime;

    @ApiModelProperty(value = "创建时间")
    private Date createTime;

}

步骤四：体验

浏览器打开：http://127.0.0.1:9090/swagger-ui.html

• 页面显示了2个接口文档
  
• 调用GET请求接口
  
• 调用POST请求接口
  
  

三、课后练习题

参考本节课内容，用springboot编写2个接口，一个是get请求，一个是post请求，然后让swagger自动生成文档。

配套学习资料

1. 课后练习作业请提交到QQ群（1号QQ群3000人已满，请加2号群：985378659[群名：SpringBoot架构师]）
2. 本课程配套免费视频教程
   https://study.163.com/course/introduction/1004576013.htm?share=1&shareId=1016481220
3. 本课程配套源码地址：https://github.com/agan-java/agan-boot