第11章 SwaggerUI企业服务文档构建

序言

1.内容介绍

​ 本章介绍了前后端分离思想架构，从而引出了SwaggerUI企业服务文档的作用，对于SpringBoot与Swagger的集成进行了详细的实现，最后引入了一个综合案例演示了如何在项目中引入Swagger企业服务文档的实现。

2.理论目标

• 掌握基于原生SQL方式进行分页结构
• 掌握自定义分页Bean的构造方式
• 掌握分页插件IPage的优势

3.实践目标

• 能熟练使用原生SQL方式，满足灵活的分页检索功能
• 能熟练使用自定义分页方式完成复杂分页功能
• 能熟练使用分页插件IPage，提升开发效率

4.实践案例

• SpringBoot集成Swagger框架实战
• 实现信息注册添加企业服务文档实战

5.内容目录

• 1.Swagger概述
• 2.SpringBoot集成Swagger
• 3.API服务文档实战

---

第1节 Swagger概述

1. 前后端分离概述

• 目前的Web项目主推采用前后端分离方式，一个项目的制作通过两个团队共同完成：
  • 后端团队开发：后端控制层、服务层、数据访问层
  • 前端团队开发：前端控制层、视图层
• 前后端通过API交互，两端相对独立且松耦合
• 前后端分离后，前端测试后端解耦通过postman软件工具
• 后端提供解耦，需要实时更新最新的消息及改动
• 前后端联系的纽带API说明文档，最合适的解决方案就是swagger

2. Swagger概述

• Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。

• 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

• 当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。

• 当开发工程师在后台的接口修改了后端，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。

第2节 SpringBoot集成Swagger

​ 前面章节已经详细讲解了持久层MyBatisPlus、SpringBoot控制层的技术点，完成了后端实际业务需求的实现，为了便于前后端分离，接下来要开始后端程序API服务接口的开发工作。首先要进行SpringBoot与Swagger的集成工作。

1. 添加Swagger依赖

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

2. 编写Swagger配置类

• swagger的配置文件所在目录如图所示：

• 注解说明
  • @Configuration：表明是一个配置类，服务启动时会自启动该注解标识的类，达到配置的效果
  • @EnableSwagger2：开启swagger,正式环境一般是需要关闭的（避免不必要的漏洞暴露！）
• 编程实现

@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("cn.com.chinahitech.springboot_user")) .paths(PathSelectors.any()) .build(); } // 构建 api文档的详细信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() // 页面标题 .title("SpringBoot基于Swagger2构建RESTful API") // 创建人信息 .contact(new Contact("作者", "网址信息", "作者邮箱")) // 版本号 .version("1.0") // 描述 .description("API描述信息") .build(); } }

3. 升级UserController

• 增加API服务文档注解

@RestController @RequestMapping("/user") @Api(value="UserController相关的api",tags = {"用户信息的Controller"}) public class UserController { @Autowired private IUserService userService; @ApiOperation(value ="分页查询",notes = "根据参数page,分页查询用户信息列表") @ApiImplicitParam(name="page",value="查看指定页",paramType = "path",required = true,dataType ="Long" ) @ApiResponses({ @ApiResponse(code=200,message="请求成功"), @ApiResponse(code=-1,message="没有检索到相关数据"), @ApiResponse(code=500,message="检索出现异常！") }) @RequestMapping(value="/selectPage/{page}",method = RequestMethod.GET) public String selectPage(@PathVariable int page) { //执行的返回结果 Map<String,Object> map = new HashMap<String,Object>(); try{ /** * Page(current,size) * current:当前页,long类型 * size:每页显示的数量,long类型 */ IPage<User> pageInfo = userService.selectPage(new Page<User>(page, 2)); if(pageInfo!=null){ map.put("status",200); map.put("data",pageInfo); }else{ map.put("status",-1); map.put("message","没有检索到相关数据！"); } }catch (Exception ex){ map.put("status","500");//执行出现异常 map.put("message","异常信息:"+ex.getMessage()); } return JSON.toJSONString(map); } }

4. 执行，观察效果

• 输入访问地址：http://localhost:8081/swagger-ui.html

• 点开接口查看方法的参数，如图所示：

• 点击"Try it out"，测试API服务接口

• 观察检索结果

第3节 API服务文档实战

1. API服务文档注解说明

API	使用范围	使用位置
@ApiModelProperty	对象属性	用于出入参数对象的字段上
@Api	协议集描述	用于Controller类上
@ApiOperation	协议描述	用于Controller方法上
@ApiResponses	Response集	用于Controller方法上
@ApiResponse	Response	用在@ApiResponses里边
@ApiImplicitParams	非对象参数集	用于Controller方法上
@ApimplicitParam	对象参数描述	用在@ApiImplicitParams的方法里边
@ApiModel	描述返回对象的意义	用在返回对象类上
@ApiInore	忽略服务注解功能	用于Controller方法上

2. 通用参数详解

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

3. @API参数说明

• @API拥有两个属性：value、tags

• 生成的api文档会根据tags分类，tags如果有多个值，会生成多个list,每个list 会显示所有接口

• tags案例说明：

  • @Api(tags = “列表1”)
  • @Api(tags = {“列表1”,“列表2”})

• value的作用类似tags， 但是不能有多个值

4. @ApiOperation

• 使用于在方法上，表示一个http请求的操作
• 常用参数
  • value：方法描述
  • notes：用于提示内容
  • tags：用于重新分组

5. @ApiParam

• 使用在方法上或参数上，字段说明
• 参数说明：
  • name：参数名
  • value：参数说明
  • required：是否必填

6. @ApiModel

• 使用在类上，表示对类进行说明，用于参数用实体类接收
• 参数说明：
  • value：表示对象名
  • description：描述

7. @ApiModelProperty

• 使用在方法，字段上，表示对model属性的说明或者数据操作更改
• 参数说明：
  • value：字段说明
  • name：重写属性名字
  • dataType：重写属性类型
  • required：是否必填
  • example：举例说明
  • hidden：隐藏

8. @ApiResponse

• 在 Rest 接口上使用，用作返回值的描述
• 参数说明：
  • code：响应的HTTP状态码
  • message：响应消息

9. 实战演练

实现信息注册

• 需求说明
  • 基于客户端传入参数信息：姓名、年龄、邮箱
• 编程实现

//save方式添加1条记录 @RequestMapping(value="/saveOne",method = RequestMethod.POST) @ApiOperation(value="添加单条用户",notes = "根据前端用户输入信息，进行添加",tags="User操作") @ApiImplicitParams({ @ApiImplicitParam(name="uname",value="用户名",required = true,paramType = "form",dataType = "String"), @ApiImplicitParam(name="age",value="年龄",required = true,paramType = "form",dataType = "Long"), @ApiImplicitParam(name="email",value="",required = true,paramType = "form",dataType = "String") }) @ApiResponses({ @ApiResponse(code=200,message="添加成功"), @ApiResponse(code=500,message="添加过程中出现异常") }) public String testSaveOneRecord(String uname,int age,String email){ //执行的返回结果 Map<String,Object> map = new HashMap<String,Object>(); try{ User user = new User(uname,age,email); userService.addUser(user); map.put("status",200); map.put("message","添加记录成功！"); }catch (Exception ex){ map.put("status","500");//执行出现异常 map.put("message","异常信息:"+ex.getMessage()); } return JSON.toJSONString(map); }

• 执行效果

开始实验