乞丐不会嫉妒国王，但会嫉妒比他更富有的乞丐。
前言
关于如何搭建SpringBoot工程以及开启Web功能，
可以查看我的这篇博客：用Spring Initializr快速构建SpringBoot及整合MVC
Swagger2
Swagger，中文翻译“神气十足”的意思，是一个功能强大的在线API文档的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。使得客户端和文件系统作为服务器以同样的速度来更新，提供了在线文档的查阅和测试功能。因本文中使用的版本为2.x，所以称之为Swagger2。
Swagger2能通过注解来生成API接口文档，文档中的信息包含接口名、请请求方法、参数、返回信息等。
一般而言，使用以下注解即可满足基本的需求用于生成在线API文档：
-
@API：修饰整个类，用于描述Controller类。 -
@ApiOperation：描述类的方法，或者说一个接口。 -
@ApiParam：单个参数描述。 -
@ApiModel：用对象来接收参数。 -
@ApiModelProperty：用对象接收参数时，描述对象的一个字段。 -
@ApiResponse：HTTP响应的一个描述。 -
@ApiResponses：HTTP响应的整体描述。 -
@ApiIgnore：使用该注解，表示Swagger2忽略这个API。 -
@ApiImplicitParam：一个请求参数。 -
@ApiImplicitParams：多个请求参数。
集成开始
1.在依赖管理文件pom.xml中引入springfox-swagger2和springfox-swagger-ui依赖：
<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>
2.在工程目录src/main/java/com/guqueyue下创建一个配置类，如：
package com.guqueyue.config;
/**
* @author guqueyue
* @Date 2020/4/12
* 配置类
**/
@Configuration // 表明是一个配置类
@EnableSwagger2 // 开启Swagger2的功能
public class Swagger2 {
@Bean // 注入一个Docket的Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 包扫描的基本包名
.apis(RequestHandlerSelectors.basePackage("com.guqueyue.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 基本文档的描述信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot利用swagger2构建api文档")
.description("简单优雅的restful风格, https://blog.csdn.net/Qizhi_Hu")
.termsOfServiceUrl("https://blog.csdn.net/Qizhi_Hu")
.build();
}
}
3.本文是根据我的上篇博客：快速CRUD的秘诀之SpringBoot整合MyBatis-Plus 改造而成，接着上篇博客在controller中添加Get、Post、Delete、Put这四种Http方法，完成对User基本的增删改查，构建一组以资源为中心的RESTful风格的API接口，如：
package com.guqueyue.controller;
/**
* @author guqueyue
* @Date 2020/4/12
**/
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
private UserServiceImpl userService;
@ApiOperation(value = "用户列表", notes = "用户列表")
@RequestMapping(value ="/list" , method = RequestMethod.GET)
public List<User> getUser() {
return userService.list();
}
@ApiOperation(value = "创建用户", notes = "创建用户")
@RequestMapping(value = {""}, method = RequestMethod.POST)
public boolean postUser(@RequestBody User user) {
return userService.save(user);
}
@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户信息")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public User getuser(@PathVariable Integer id) {
return userService.getById(id);
}
@ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
public boolean putUser(@PathVariable Integer id, @RequestBody User user) {
User user1 = new User()
.setUsername(user.getUsername())
.setPassword(user.getPassword())
.setId(user.getId());
return userService.updateById(user1);
}
@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
public String deleteUser(@PathVariable Integer id) {
userService.removeById(id);
return "success";
}
@ApiIgnore // 使用该注解忽略这个API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return "hi guqueyue!";
}
}
通过@ApiOperation注解描述生成具体API的说明，其中value值为该接口的名称，notes值为该接口的详细文档说明；若是不需要某接口生成文档，使用@ApiIgnore注解忽略即可，这样就可以生成在线的API接口文档。
4.启动应用程序，打开浏览器，输入"http://localhost:8080/swagger-ui.html"，即可显示Swagger-UI在线文档的界面：
