SpringBoot整合Swagger2

文章原地址：
https://blog.csdn.net/Qizhi_Hu/article/details/105484014

前言

关于如何搭建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在线文档的界面：