1. Swagger的概念

Swagger是一款目前世界最流行的API管理工具。目前Swagger已经形成一个生态圈，能够管理API的整个生命周期，从设计、文档到测试与部署。

尤其擅长管理基于Restful的WebService接口。

Swagger有几个重要特性：

代码侵入式注解
遵循YAML文档格式
非常适合三端（PC、iOS及Android）的API管理，尤其适合前后端完全分离的架构模式
减少没有必要的文档，符合敏捷开发理念
功能强大

2. Swagger的作用

接口的文档在线自动生成
功能测试

3. Swagger的优势

大大减少前后端的沟通
方便查找和测试接口
提高团队的开发效率
方便新人了解项目

4. Swagger的使用

4.1 引入依赖

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

4.2 编写Swagger配置类

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.lijinghua")) //swagger搜索的包.paths(PathSelectors.any()) //swagger路径匹配.build();}//api文档信息private ApiInfo apiInfo() {return new ApiInfoBuilder().title("文件上传文档")//文档标题.description("使用FastDfs文件上传")//文档说明.version("version 1.0")//版本信息.build();}
}

4.3 测试

5.Swagger常用注解

我们可以通过Swagger注解，侵入式地、更详细地、具体地对API进行说明。

5.1 测试代码

5.1.1 UserController类

@RestController
@RequestMapping("/user")
@Api(tags = {"用户管理API"})
public class UserController {@PostMapping@ApiOperation(value = "新增用户", notes = "新增后返回当前用户")@ApiResponses({@ApiResponse(code = 200, message = "返回成功", response = User.class),@ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),@ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),})public ResponseEntity<User> add(User user) {if (user.getId() == 1) {return new ResponseEntity<>(user, HttpStatus.BAD_REQUEST); //400} else if (user.getId() == 2) {return new ResponseEntity<>(user, HttpStatus.UNAUTHORIZED); //401} else {return ResponseEntity.ok(user);}}@PutMapping@ApiOperation(value = "修改用户", notes = "修改后返回当前用户")@ApiResponses({@ApiResponse(code = 200, message = "返回成功", response = User.class),@ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),@ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),})public ResponseEntity<User> update(User user) {if (user.getId() == 1) {return new ResponseEntity<>(user, HttpStatus.BAD_REQUEST); //400} else if (user.getId() == 2) {return new ResponseEntity<>(user, HttpStatus.UNAUTHORIZED); //401} else {return ResponseEntity.ok(user);}}@DeleteMapping("/{id}")@ApiOperation(value = "删除用户", notes = "删除后返回当前id")@ApiResponses({@ApiResponse(code = 200, message = "返回成功", response = User.class),@ApiResponse(code = 400, message = "参数没有填好(id==1)", response = User.class),@ApiResponse(code = 401, message = "权限不足(id==1)", response = User.class),})@ApiImplicitParam(paramType = "path", name = "id", value = "用户主键ID", required = true)public ResponseEntity<Long> delete(@PathVariable Long id) {if (id == 1) {return new ResponseEntity<>(id, HttpStatus.BAD_REQUEST); //400} else if (id == 2) {return new ResponseEntity<>(id, HttpStatus.UNAUTHORIZED); //401} else {return ResponseEntity.ok(id);}}@GetMapping("/{id}")@ApiIgnorepublic ResponseEntity<Long> toUpdate(@PathVariable Long id) {if (id == 1) {return new ResponseEntity<>(id, HttpStatus.BAD_REQUEST); //400} else if (id == 2) {return new ResponseEntity<>(id, HttpStatus.UNAUTHORIZED); //401} else {return ResponseEntity.ok(id);}}@PostMapping("/list-page")@ApiOperation(value = "分页查询", notes = "得到分页查询对象pageInfo")@ApiImplicitParams({@ApiImplicitParam(paramType = "query", name = "pageNum", value = "当前页", required = false, defaultValue = "1"),@ApiImplicitParam(paramType = "query", name = "pageSize", value = "每页行数", required = false, defaultValue = "10")})public ResponseEntity<String> findByPage(@RequestParam(defaultValue = "1", required = false)Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) {return ResponseEntity.ok("find page result...");}
}

5.1.2 User实体类

@Data
@ApiModel("用户对象模型")
public class User {private Long id;private String username;private String password;private String email;
}

5.2 @Api()

用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源。它有几个参数：

tags：说明该类的作用，参数是个数组，可以填多个。
value：该参数没什么意义，在UI界面上不显示，所以不用配置。
description ：用户基本信息操作（已被废弃）。

5.3 @ApiOperation()

用于方法，表示一个http请求访问该方法的操作。它有几个参数：

value：方法的用途和作用。
notes：方法的注意事项和备注。
tags：说明该方法的作用，参数是个数组，可以填多个。

格式：tags={“作用1”,“作用2”}，（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）。

5.4 @ApiModel()

用于响应实体类上，用于说明实体作用。参数：

description：描述实体的作用。

5.5 @ApiModelProperty()

用在属性上，描述实体类的属性。它有几个参数：

value：描述参数的意义。
name：参数的变量名。
required：参数是否必选。

5.6 @ApiImplicitParams()

用在请求的方法上，包含多@ApiImplicitParam。

5.7 @ApiImplicitParam()

用于方法，表示单独的请求参数，它有几个参数：

name：参数名。
value：参数说明。
dataType：参数的数据类型。
paramType：表示参数放在哪里。
- header 请求参数的获取：@RequestHeader
- query 请求参数的获取：@RequestParam
- path（用于restful接口）请求参数的获取：@PathVariable
- body（不常用）
- form（不常用）
defaultValue：参数的默认值。
required：表示参数是否必须传。

5.8 @ApiParam()

与@ApiImplicitParam()作用基本相同，但是功能较弱，用于方法、参数，它有几个参数：

name：参数名。
value：参数说明。
defaultValue：参数的默认值。
required：表示参数是否必须传。

5.9 @ApiResponses

用于请求的方法上，根据响应码表示不同响应，一个@ApiResponses包含多个@ApiResponse。

5.10 @ApiResponse

用在请求的方法上，表示不同的响应，它有几个参数：

code：表示响应码(int型)，可自定义。
message：状态码对应的响应信息。

5.11 @ApiIgnore()

用于类或者方法上，不被显示在页面上。

API管理工具-Swagger相关推荐

API 管理工具 Swagger 和 RAP 的比较
# 概述微服务在当今的 web 开发中越来越盛行,前后端分离现在似乎也已成为中大型 Web 工程的基本模式,如何建立好前端调用和后端接口 (或者服务调用方和 API 提供方) 之间的契约,妥善处理好 ...
Api管理工具（spring-rest-docs）
对于app开发来说,必须需要有相应的api文档,一般最基础的就是用markdown工具来撰写api文档.当对于开发人员来说,是总会想着寻找更方便撰写,测试,对接前端开发的文档生成的工具. 其实这方面的 ...
超全开放 API 免费调用，这款 API 管理工具太香了！
01 此前时不时会有一些研发小伙伴和我诉苦,说很多企业由于人力财力限制或者需求不强,会直接购买使用第三方的开放API,这样一来, 一则由于开放项目不是量身定制的,寻找自己合适的接口也要搜索调研蛮多时间 ...
推荐一款可以替代 Postman 的国产 api 管理工具 apipost
做开发的朋友们相信对于 api 测试工具不陌生,用测试工具可以直接进行项目测试而不用等前端写好压面来测试. 像之前很多人都使用的是国外的 Postman,那款软件伴随了许多程序员.不过他对于新手来说不 ...
Apipost和 Apifox 哪个好用？两大国产API管理工具深度对比
Apipost和 Apifox 哪个好?这两款国产API 管理工具的推广力度那叫一个猛,就鬼打墙似的,我在哪个公众号都能看到他们两家的推广. 我内心OS 就是: 只有充分内卷,才能够把厂商们的平均水平 ...
介绍几款常用的在线API管理工具
在项目开发过程中,总会涉及到接口文档的设计编写,之前使用的都是ms office工具,不够漂亮也不直观,变更频繁的话维护成本也更高,及时性也是大问题.基于这个背景,下面介绍几个常用的API管理工具,方 ...
API管理工具对比，制定您的API管理平台
有一定工作年限的人一定会接触过通过word文档或者wiki的方式来进行接口对接交流的介质.后来为了方便协作修改接口,又逐渐的开始有人通过markdown文档,提交到版本管理系统的方式来编写接口. 后来 ...
FREE 开源 API 管理工具等
最近学习API 管理工具,发现几个不错的东西,记录如下: 1.IBM 收购NODE 厂家 STRONGLOOP 有一产品LOOPBACK,开源,好! 2.apigee api管理平台也不错. 3 ...
介绍两款API管理工具
2019独角兽企业重金招聘Python工程师标准>>> 介绍.收藏两款API管理工具: 1) AMP, https://github.com/gomeplusFED/AMP 2) 小 ...

API管理工具-Swagger