Swagger入门教程

一、Swagger简介

1、前后端分离

Vue + SpringBoot

后端时代：前端只用管理静态页面；html==>后端。模板引擎 JSP=>后端是主力

2、前后端分离时代

• 后端：后端控制层，服务层、数据访问层【后端团队】
• 前端：前端控制层，视图层【前端团队】
  • 伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来。
• 前后端如何交互？====>API
• 前后端相对独立，松耦合；
• 前后端甚至可以部署在不同的服务器上

3、产生一个问题

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

解决方案：

• 首先提出schema【计划的提纲】，实时更新最新的API，降低集成的风险；
• 早些年：指定word文档
• 前后端分离：
  • 前端测试后端接口
  • 后端提供接口，需要实时更新最新的消息及改动

4、Swagger

• 号称世界上最流行的API框架；
• RestFul Api文档在线自动生成工具=>==Api文档与API定义同步更新==
• 直接运行，可以在线测试API接口
• 支持多种语言：Java，PHP
• 官网： https://swagger.io/

二、SpringBoot集成Swagger

2. 导入相关依赖

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

3. 配置swagger==>Config

   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   //最基本配置
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
   }
   

4. 测试运行： http://localhost:port/swagger-ui.html

三、注解说明

@Api() : 用于类

• 表示标识这个类是swagger的资源

• MIME(Multipurpose Internet Mail Extensions)：多用途互联网邮件扩展类型。是设定某种扩展名的文件用哪一种应用程序来打开的方式类型，当该扩展名文件被访问的时候，浏览器会自动使用指定应用程序来打开。多用于指定一些客户端自定义的文件名，以及一些媒体文件打开方式。
• ws：WS是website的缩写，即网址的意思。具有比.COM更广泛的适用性。
• wss：Windows SharePoint Services (WSS)是一个用来创建能够实现信息共享和文档协作的Web站点的引擎，从而有助于提高个人和团队的生产力。它是Microsoft Windows Server™ 2003中所提供的信息工作者体系结构的重要组成部分， 为Microsoft Office System和其他的桌面应用程序提供了附加的功能，并能够作为应用程序开发的平台。

@Api(protocols = "http", tags = {"模型controller"})
public class MOdelController {}

@ApiOperation() : 用于方法

• 说明方法的用途、作用。

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

@ApiParam() : 用于方法参数、字段说明

• 一般用在请求体参数上，描述请求体信息

@ApiOperation(value = "新增用户")
public Boolean insert(@RequestBody @ApiParam(name = "UserDTO", value = "新增用户参数") UserDTO userDTO) {
    list.add(userDTO);
    return true;
}

@ApiImplicitParams：用在请求方法上

• 表示一组参数的说明，里面是@ApiImplicitParam列表

@ApiImplicitParam

@GetMapping("page")
@ApiOperation(value = "分页查询问题列表")
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNum", value = "当前页数"),
    @ApiImplicitParam(name = "pageSize", value = "每页记录数")
})
public List<UserDTO> page(
    @RequestParam(defaultValue = "1", required = false) 
    Integer pageNum, 
    @RequestParam(defaultValue = "10", required = false) 
    Integer pageSize) {
  
    return list;
}

@ApiResponses: 用在请求的方法上

• 表示一组响应，里面是@APIResponse

@ApiResponse

• 一般表达一种错误的响应信息

@PutMapping
@ApiOperation(value = "更新用户信息")
@ApiResponses({
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
public Boolean update(@RequestBody @ApiParam(name = "UserDTO", value = "更新用户参数") UserDTO userDTO){}

@ApiModel: 用在实体类型上

• 表示相关实体的描述

@ApiModel(value = "用户", description = "查询用户")
public class UserDTO implements Serializable{}

@ApiModelProperty: 用在实体类属性上

• 表示属性的相关描述

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

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