Swagger的简介

目前大部分的项目都是前后端分离的，后端除了要提供接口外，还需要提供接口文档，有时由于需求、设计或方案的变更，会造成接口变更但是接口文档没有及时更新的情况。Swagger是一个在你写接口的时候帮你自动生成接口文档，并且文档会随着接口的变化而变化的东西，只要你遵循它的规范并写一些接口的说明注解即可。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务的接口文档。下面我们通过一个实例来看一下Swagger的使用。

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. 配置Swagger

创建Swagger配置类：

// 标明是配置类
@Configuration
// 开启Swagger功能
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 构建一个Docket Bean
     * @return
     */
    @Bean
    public Docket createRestapi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 页面展示信息
                .apiInfo(apiInfo())
                // 返回一个ApiSelectorBuilder实例，用来控制接口被Swagger做成文档
                .select()
                // 用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                // 选择所有的API，如果你只想为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 定义api文档主页面的基本信息
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Swagger test")
                .description("API描述")
                // 版本号
                .version("1.0")
                .build();
    }

}

3. 创建User实体类

@ApiModel: 用来标注实体类，常用配置项：

• value: model的别名，默认为类名

• description: model的详细描述

@ApiModelProperty: 用来标注实体类的字段，常用配置项：

• value: 字段说明

• example: 字段的示例值

• required: 是否为必填项

@Data
@ApiModel(description = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户id")
    private Integer id;

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

}

4. 创建测试类和方法

@Api: 用在类上，该注解将一个Controller（Class）标注为一个Swagger资源（API），常用配置项：

• tags: API分组标签，具有相同标签的API将会被归并在一组内展示

• value: 如果tags没有定义，value将作为Api的tags使用

@ApiOperation: 用来描述接口，常用配置项：

• value: 接口的简单说明

• notes: 接口的详细说明

@ApiParam: 接口参数的说明，常用配置项：

• required: 是否必填，默认为false

• value: 参数说明

@RestController
@RequestMapping("user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("get")
    @ApiOperation(value = "获取用户信息")
    public User get(@ApiParam(value = "用户id", required = true) @RequestParam Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("张三");
        return user;
    }

}

5. 访问host+swagger-ui.html

可点开用户管理和Models查看更详细的接口信息：

Swagger UI增强

swagger-bootstrap-ui是springfox-swagger的增强UI实现，这个ui的api文档结构更加清晰，在线调试也很方便。

增加以下依赖：

<dependency> 
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>swagger-bootstrap-ui</artifactId> 
    <version>1.9.6</version> 
</dependency>

增加swagger-bootstrap-ui依赖后，访问host+doc.html，页面展示如下：

Swagger的优缺点

优点：

1.自动生成文档：只需要在接口中使用注解进行标注，就能生成对应的接口文档

2.自动更新文档：由于是动态生成的，所以如果研发修改了接口（如果也更新了注解的话），文档也会自动对应修改

3.支持在线调试：Swagger支持在线调试接口

缺点：

1.不能创建测试用例：Swagger只能提供一个简单的在线调试，如果你想存储你的测试用例的话，可以使用Postman或者YAPI

2.没有接口文档版本管理：文档更新后，就看不到旧版的接口文档了

Swagger的注意事项

1. 线上环境（外网环境）记得关闭

否则接口的信息就全部暴露在外网了

2. 推荐返回实体类，而不是Map格式

Swagger不能对Map格式返回数据的每个字段做说明，可以对实体类的属性增加说明，故推荐返回实体类，而不是Map格式的数据

若您觉得还可以，请帮忙点个“赞”，谢谢～

关注我，查看更多技术干货文章