SpringBoot集成Swagger2

一、引言

经历过调用接口但定义好的接口被修改且没有更新接口文件的痛苦，你才能体会到Swagger2的好。话句话说，有时候定义了接口文档，代码中修改了一点小的东西，但总会忘记同步修改接口文档，时间长了，就连自己都会比较蒙，还需要看一下代码才能发现问题，让别人情何以堪呢？

如今，前后端分离已经成为一种标准的开发方式，前端与后端交给不同的人员开发，各司其职。
但是开发中的相互间的沟通成本也随之提高，这部分沟通成本主要在于前端开发人员与后端开发人员对 WebAPI 接口的沟通。Swagger2 可以根据接口修改，动态的生成Api接口文档，这样就可以降低沟通成本，促进项目高效开发。

下面就来学习一下Swagger2吧。

二、Swagger2介绍

在介绍Swagger2之前，先来了解一下OpenAPI规范。

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

https://github.com/OAI/OpenAPI-Specification

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。

https://swagger.io/

Spring Boot 可以集成Swagger，生成Swagger接口，需要添加如下依赖即可。

 	
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger2artifactId>
        <version>2.9.2version>
    dependency>
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger-uiartifactId>
        <version>2.9.2version>
    dependency>

创建一个Swagger2配置类，并要开启Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }
    
    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("用户中心API文档")
                .description("本文档描述了用户中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("scorpios", "http://127.0.0.1", "[email protected]"))
                .build();
    }
}

要在启动类上标注注解扫描：@ComponentSacn(basePackages = {“com.scorpios”})

三、Swagger2注解

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

1、@Api

使用：修饰整个类，描述Controller的作用

@RestController
@RequestMapping("/swagger")
@Api(value = "swagger2的demo例子")
public class SwaggerController {
    
}

2、@ApiOperation

使用：用于描述一个方法或者接口

可以添加的参数形式：

 @ApiOperation(value = “接口说明”, 
			 httpMethod = “接口请求方式”, 
			response = “接口返回参数类型”, 
			notes = “接口发布说明”）

@RequestMapping("/swagger")
@ResponseBody
@ApiOperation(value = "根据用户名获取用户的信息",
				notes = "查询数据库中的记录",
				httpMethod = "POST",
				response = String.class)
    public String getUserInfo(String userName) {
        return "1234";
    }
}

3、@ApiImplicitParam

使用：一个请求参数

@ApiImplicitParam(
	required = “是否必须参数”, 
	name = “参数名称”, 
	value = “参数具体描述”,
	dateType=“变量类型”,
	paramType=”请求方式”）

@ApiImplicitParam(name = "userName",
	value = "用户名",
	required = true,
	dataType = "String",
	paramType = "query")
    public String getUserInfo(String userName) {
        return "1234";
    }
}

5、@ApiImplicitParams

使用：多个请求参数

参数和@ApiImplicitParam一致，只是这个注解可以添加多个参数而已

@ApiImplicitParams(
	{
    	@ApiImplicitParam(name = "nickName",
    		value = "用户的昵称",
    		paramType = "query",
    		dataType = "String",
    		required = true),
    	@ApiImplicitParam(name = "id",
    		value = "用户的ID",
    		paramType = "query",
    		dataType = "Integer",
    		required = true)
})
public String getUserInfoByNickName(String nickName, Integer id) {
    return "1234";
}

其他注解使用如下：

@Api(tags = "提供用户的增删改查的功能")
@RestController
public class UserController {
    @Autowired
    private UserService userService;

    @ApiOperation(value = "添加用户")
    @RequestMapping(value = "/addUser", method = RequestMethod.POST)
    public String addUser(User user) {
        try {
            userService.addUser(user);
            return "添加用户成功";
        } catch (Exception e) {
            return "添加用户失败:" + e.getMessage();
        }
    }

    @ApiOperation(value = "删除用户")
    @RequestMapping(value = "/addUser", method = RequestMethod.DELETE)
    public String delUser(int id) {
        try {
            userService.delUser(id);
            return "删除用户成功";
        } catch (Exception e) {
            return "删除用户失败:" + e.getMessage();
        }
    }

    @ApiOperation(value = "更新用户")
    @RequestMapping(value = "/updateUser", method = RequestMethod.PUT)
    public String updateUser(User user) {
        try {
            userService.updateUser(user);
            return "更新用户成功";
        } catch (Exception e) {
            return "更新用户失败:" + e.getMessage();
        }
    }

    @ApiOperation(value = "查询用户")
    @RequestMapping(value = "/findAll", method = RequestMethod.GET)
    public List<User> findAll() {

        return userService.findAll();

    }
}

运行程序 ：http://localhost:8080/swagger-ui.html

展开接口内部

点击try it out 输入姓名， Execute执行，返回如下图效果

查看数据库表，数据已经添加到数据库

每次只要我们修改接口参数，Swagger2接口都会动态更新，只需要重新查看就好了。