Swagger使用记录

1、背景

在进行前后端分离项目开发时，前后端代码由不同人员进行开发，要想成功的进行前后端联调，开发时必须规范开发接口。接口文档的编写工作通常由后端人员完成，接口文档中必须包含接口说明、请求url、请求参数、请求方法、响应数据说明这五个部分。然而手动编写接口文档比较繁琐，接下来我们介绍使用Swagger编写接口文档…

2、接口概念

百度百科中的概念：应⽤程序编程接⼝，简称API（Application Programming Interface），就是软件系统不同组成部分衔接的约定。
狭义的理解：就是控制器中可以接受⽤户请求的某个⽅法。

3、Swagger介绍

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 (https://swagger.io/)
Swagger是⼀个⽤于⽣成服务器接⼝的规范性⽂档、并且能够对接⼝进⾏测试的⼯具。

4、pom.xml文件中引入Swagger相关依赖

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

5、编写SwaggerConfig配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * Swagger会帮我们生成接口文档
     * 1：配置生成的文档信息
     * 2：配置生成规则
     */

    /**
     * Docket封装接口文档信息
     *
     * @return Docket
     */
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                //指定生成的文档中的封面信息：文档标题、版本、作者
                .apiInfo(getApiInfo())
                .select()
                //.apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
                // 第二种写法：扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加封面信息
     *
     * @return ApiInfo
     */
    private ApiInfo getApiInfo() {
        //创建封面信息对象
        return new ApiInfoBuilder()
                //设置标题
                .title("《xx项目》后端接口文档")
                //描述
                .description("此文档详细说明了xx项目后端接口规范....")
                //作者信息
                .contact(new Contact("xx", "www.xx.com", "150xxxxxxxx@163.com"))
                //版本
                .version("v2.0.1")
                .build();
    }
}

配置完成好后重启项目，然后访问 http://ip:port/swagger-ui.html 即可看到Swagger帮我们生成的接口文档。

6、Swagger常用注解介绍

注解	位置	作用
@Api	类注解	在控制器类添加此注解，可以对控制器类进⾏功能说明
@ApiOperation	方法注解	说明接口的作用
@ApiImplicitParams	方法注解	说明接口的参数(多参数时使用)
@ApiImplicitParam	方法注解	说明接口的参数
@ApiModel	类注解	加在实体类上，说明实体类
@ApiModelProperty	属性注解	加在实体类属性上，说明属性
@ApiIgnore	方法注解	添加此注解的⽅法将不会⽣成到接⼝⽂档中

注：@ApiModel 和 @ApiModelProperty 当接⼝参数和返回值为对象类型时，在实体类中添加注解 说明

@ApiImplicitParam属性：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

举例：

@RestController
@RequestMapping("/user")
@Api(value = "提供用户的登录和注册接口", tags = "用户管理")
public class UserController {

    @Resource
    private IUserService userService;

    @ApiOperation("用户登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name="username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType = "string",name="password",value = "用户登录密码",defaultValue = "111111")
    })
    @GetMapping("/login")
    public ResultVO login(@RequestParam("username")String username,
                          @RequestParam(value = "password",defaultValue = "111111")String password) {
        return new ResultVO(10001, "", null);
    }

    @ApiOperation("用户注册接口")
	//@ApiImplicitParam(value = "用户信息",required = true)
    @PostMapping("/register")
    public ResultVO register(Users user) {
        return new ResultVO(10001, "", null);
    }
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "User对象", description = "用户信息")
public class Users {

    @ApiModelProperty(dataType = "int", required = false)
    private Integer userId;

    @ApiModelProperty(dataType = "String", required = true, value = "用户名")
    private String username;

    @ApiModelProperty(dataType = "String", required = false, value = "用户密码")
    private String password;
}

7、Swagger-ui插件

为了使Swagger生成的文档更加美观，我们引入Swagger-ui的插件。

7.1、pom.xml文件中引入依赖

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

7.2、重启项目后，访问路径为http://ip:port/doc.html