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

作者: 阿甘java | 来源:发表于2019-11-04 00:28 被阅读0次

使用springboot集成swagger2遇到的问题总结
第08课：用swagger为SpringBoot生成接口文档
怎么管理接口文档
SpringBoot指南|第四篇：集成swagger生成API文
教你一步一步集成swagger
用Swagger生成接口文档
Springboot系列（七）配置接口文档swagger
[java]62、Swagger
SpringBoot集成Swagger2在线文档
抛弃swagger，不写注解生成接口文档

一、本课程目标：

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

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

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

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

自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
跨语言性，支持 40 多种语言。
Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
还可以将文档规范导入相关的工具（例如 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的常用注解：

image

以下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;

}