1 Swagger2

1.1 Swagger2简介

Swagger2–自动生成接口文档

优点：

1. 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。

2. 跨语言性，支持 40 多种语言。

3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

4. 还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。
   Swagger是一套围绕Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。

1.1 Swagger2引入

前后端分离：

• 后端：后端控制层，服务层，数据访问层【后端团队】

• 前端：前端控制层，视图层【前端团队】

• • 伪造后端数据 Json，不需要后端，程序依旧能运行

• 前后端如何交互？===> API

• 前后端相对独立，松耦合

• 前后端甚至可以部署在不同的服务器上

• 后端提供接口，需要实时更新最新的消息及改动！

前后端分离产生一个问题：

• 前后端继承联调，前端人员和后端人员无法做到，及时协商，尽早解决。最终导致问题集中爆发！

解决方案：

• 指定一个schema (计划或理论的提要，纲要）实时更新最新的API，降低集成的风险

• 早些年：制定world计划文档。

• 前后端分离：

• • 前端测试后端接口：postman
    • 后端提供接口，需要实时更新到最新的消息及改动。

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。

很多程序员会抱怨别人写的接口文档不规范，不及时更新。但自己写的时候也觉得烦——太痛苦了。如果接口文档可以实时动态生成就不会出现上面问题。

Swagger可以完美解决上面的问题。

1.2 Swagger 工具包括的组件

Swagger 工具包括的组件：

• Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。（用的比较少，自定义配置时才用）
• Swagger UI： 将Open API 规范呈现为交互式API文档。用可视化 UI展示描述文件。(通过浏览器，根据代码中的 注解 查看)
• Swagger Codegen：将OpenAPI 规范成为服务器存根（可以生成文件，方便访问服务器信息，快速展示）和客户端库。通过Swagger Codegen 可以将描述文件生成html格式和cwiki形式的文档接口，同时也可以生成多种言语的客户端和服务段代码。
• Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息（多了过程记录），也会保存请求时及参数数据。
• Swagger Hub：继集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub 中可以帮助完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用Swagger，就是把相关信息存储在它定义的描述文件里面(yml和json格式)，再通过维护整个描述文件可以去更新接口文档，以及生成各端代码。

• Swagger号称世界上最流行的Api框架
• 通过Swagger给一些比较难理解的属性或者接口添加注释信息
• Rest Api 文档在线自动生成工具 -> Api文档与Api定义实时更新
• 直接运行，可以在线测试API接口
• 支撑多种语言：（Java，PHP…）

2 Spring整合使用Swagger2

2.1 导入依赖

<!-- 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>

2.2 Swagger2Config配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket getDocket(){
        //创建Docket对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())//指定API接口文件首页信息
                .select()//初始化并返回一个API选择构造器
                .apis(RequestHandlerSelectors.any())//为任何接口生成API文档
                .paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build(); //创建API文档
        return docket;
    }
    private ApiInfo getApiInfo(){
        //创建作者 对象
        Contact contact = new Contact("尼古拉斯","http://www.baidu.com","[email protected]");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("《麦淘乐后端接口文档》") //文档标题
                .description("文档的描述信息...")//文档描述
                .contact(contact)//文档作者
                .version("V1.0")//文档版本
                .build(); //构建
        return apiInfo;
    }
}

2.3 测试

启动SpringBoot项目访问：http://localhost:8888/swagger-ui.html

3 Swagger2常用注解

3.1 Controller注解

• @Api：修饰整个类，描述Controller的作用
  • tags:“说明该类的作用”

@RestController
@RequestMapping("users")
@Api(tags = "用户管理API")
public class UserController {
    //TODO
}

3.2 方法注解

• @ApiOperation：描述一个类的一个方法(一个接口)
  • value=“说明方法的作用”
  • notes=“方法的备注说明”
• @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
• @ApiImplicitParam ：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
  • name：参数名
  • value：参数的汉字说明、解释
  • required：参数是否必须传
  • dataType ：参数类型，默认String，其它值dataType=“int”
  • defaultValue：参数的默认值
  • paramType：参数放在哪个地方
    • header --> 请求参数的获取：@RequestHeader
    • query --> 请求参数的获取：@RequestParam
    • path（用于restful接口）–> 请求参数的获取：@PathVariable
    • body（请求体）–> @RequestBody User user
    • form（普通表单提交）

@ApiOperation(value="用户登录",notes="备注：手机号码唯一")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true),
        @ApiImplicitParam(name="password",value="密码",required=true)
})
@PostMapping("/login")
public ResultVO login(@RequestParam String mobile, @RequestParam String password){
    //TODO
}

3.3 实体类注解

• @ApiModel：用对象来接收参数时,用于描述对象（实体类中的注解）
  • （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）
• @ApiProperty：用对象接收参数时，描述对象的一个字段（实体类中属性的注解）

@Data
@NoArgsConstructor
@AllArgsConstructor
                                     
    @ApiModelProperty(value = "用户ID",example = "1")
    private Integer id;
    @ApiModelProperty(value = "登录账户",example = "1")
    private String username;
    @ApiModelProperty(value = "账户密码",example = "1")
    private String password;
}

3.4 方法返回值注解

• @ApiResponses：方法返回对象的说明
  • @ApiResponse：每个参数的说明
    • code：数字，例如400
    • message：信息，例如"请求参数没填好"

@ApiResponses({
    @ApiResponse(code = 200,message = "请求成功"),
    @ApiResponse(code = 201,message = "请求失败，参数错误"),
    @ApiResponse(code = 202,message = "请求失败，未知错误")
})

3.5 忽略方法

• @ApiIgnore:接口方法注解，添加此注解的方法将不会生成到接口文档中

3.6 swagger-ui插件

导入依赖

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

访问地址：http://localhost:8888//swagger-ui.html

3.7拦截器放行swagger2资源

.excludePathPatterns("/swagger-ui.html","/webjars/**","/swagger-resources/**","/v2/**");