SpringBoot集成Swagger2的demo

很多开发人员都不喜欢写文档！在他们根深蒂固的观念中，写文档就是浪费时间，还不如直接写代码酣畅淋漓的痛快！尤其是对于Java后台开发人员而言，维护一份接口文档，更是一件痛不欲生的事情！接口太多了，变化太多了，改完代码还要改文档。流程不规范的团队，经常会出现这样的情况：有时候接口代码变了，文档没有及时更新，前端开发人员不知道；有时候是后台开发人员直接与前端开发人员私下商量一致，直接更新代码不更新文档，久而久之，文档就是去了作用，成了摆设。另外，接口测试工作要借助类似Postman的第三方工具。但事与人违，文档是交流沟通的媒介，文档是项目验收的必备材料，文档是知识和经验的积累！每一个开发人员无法避免的一项工作，就是写文档！

那么，有没有什么工具能够帮助我们自动生成接口文档呢？懒人自有天助吧！Swagger帮助我们解决以上困惑。那我们现在就开启SpringBoot集成Swagger的道路吧。
首先必不可少的当然是Swagger的依赖了，当然Swagger的依赖版本有很多，需要选择与自己jdk对应的版本，如果不知道是哪个版本，不妨多试几个版本，这里用的版本是2.7.0的，具体如下：

<!--swagger2依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

添加完对应的依赖后，我们需要编写Swagger的配置文件了，这个配置文件不需要我们去强记，我们只需要知道里面基本需要配一些什么就可以了，因为这个一个项目只需要配置一次，而且很多东西都是死了，所以不需要强记，只需要理解即可。
Swagger配置文件代码如下：

package com.itds.swagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage("com.itds.swagger.controller")) // 对所有api进行监控
                // 配置仅适用了@ApiOperation注解的方法，被Swagger管理
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()) // 对所有路径进行监控
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("DaoShuai", "http://www.baidu.com", ""))
                //版本号
                .version("v1.0")
                //描述
                .description("Swagger2 API")
                .build();
    }
}

这里一定要加上@Configuration的注解，如果忘记了的话就会出问题，具体是什么问题，大家可以去试一试，只有自己亲自体验到了才会更加深刻。
既然这个是针对接口API的，那么我们一定就需要控制器了，因为这个只是一个入门的小demo所以案例里的数据都是人造的(就是没有进行数据库查询的，要是需要数据库里的数据，大家可以等熟练入门操作后自行升级)。案例中编写了两个接口，分别是获取用户列表以及根据id获取用户的接口，在编写控制器接口前我们需要编写一个用户的类。
用户类如下：

package com.itds.swagger.model;

import lombok.Data;

@Data
public class User {

    private Integer id;

    private String username;

    private String password;

    private Integer sex;

    private String mial;

    private String phone;
}

其中使用了一个@Data的注解，这个注解是一个自动生成get、set方法的注解，这样便省去了我们很多的硬编码。使用该注解前需要引入一个jar依赖。依赖如下：

<!--lomnok包导入-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.18</version>
        </dependency>

编写完实体类后接着就是编写控制器了。控制器的代码如下：

package com.itds.swagger.controller;

import com.itds.swagger.common.ResultMessage;
import com.itds.swagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;

import java.util.ArrayList;
import java.util.List;

@Api(tags = "用户接口")
@Controller
@RequestMapping("user")
public class UserController {

    @ApiOperation(value="获取用户列表详细信息", notes="获取用户列表详细信息")
    @PostMapping("/getAll")
    public ResultMessage getAll(){
        List<User> users = new ArrayList<>();
        User user1 = new User();
        user1.setId(1);
        user1.setUsername("user1");
        user1.setPassword("123456");
        user1.setSex(1);
        user1.setMial("837182410@qq.com");
        user1.setPhone("110");

        User user2 = new User();
        user2.setId(2);
        user2.setUsername("user2");
        user2.setPassword("123456");
        user2.setSex(2);
        user2.setMial("837182411@qq.com");
        user2.setPhone("120");

        users.add(user1); users.add(user2);

        return new ResultMessage(ResultMessage.Success,"查询成功",users);
    }

    @ApiOperation(value="根据url的id获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @GetMapping("/getById/{id}")
    public ResultMessage getById(@PathVariable(value = "id") Integer id){
        if(id == 1){
            User user1 = new User();
            user1.setId(1);
            user1.setUsername("user1");
            user1.setPassword("123456");
            user1.setSex(1);
            user1.setMial("837182410@qq.com");
            user1.setPhone("110");
            return new ResultMessage(ResultMessage.Success,"查询成功",user1);
        }else{
            return new ResultMessage(ResultMessage.Fail,"查询失败");
        }
    }
}

@Api(tags = “用户接口”)这个注解就是解释这个控制器是什么控制器，里面的内容是"用户接口"则生成swagger文档的时候便可以看到对应的信息，而在这个控制器下的接口就会显示在"用户接口"下面，到时候生成的swagger可以去看一看。
@ApiOperation(value=“获取用户列表详细信息”, notes=“获取用户列表详细信息”)这个注解就是解释这个接口是什么意思。
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Integer”, paramType = “path”)这个注解就是解释说明传入的参数的。
最后便是启动类了，启动类需要加一个@EnableSwagger2的注解，代码如下：

package com.itds.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

最后运行启动类，启动完毕后，访问http://localhost:8080/swagger-ui.html#!/地址即可看到Swagger和对应的接口。
效果如图：

案例下载链接：https://download.csdn.net/download/qq_41171482/11259566