Spring Boot 集成swagger2

功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。
根据自身的接口和以及自身需求
首先新建一个Spring项目于

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency><dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

加入上面所要导入的包，然后再启动类里面直接进行设置，首先配置启动类：

package com.example.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.google.common.base.Predicate;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static com.google.common.base.Predicates.*;

@SpringBootApplication
@EnableSwagger2 //启用swagger
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

    /**
     * 这里是可以分组定义多个Docket，我这里举例定义了两个，一个是业务文档类型，一个是财务文档类型。
     * 定义了多个分组后，在页面上提供了一个下拉来选择组，具体运行起来看看就知道了。
     * 我这个是参照官方的代码改了改，有的删了，具体的大家看官方文档吧，
     * 地址：http://springfox.github.io/springfox/docs/current/#plugins-available-for-extensibility
     *
     */

    /**业务文档*/
    @Bean
    public Docket businessDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("业务文档") //分组名称
                .select()
                .paths(businessPaths()) //指定路径处理PathSelectors.any()代表所有的
                .build()
                .apiInfo(apiInfo());
    }
    @SuppressWarnings("unchecked")
    private Predicate<String> businessPaths() {
        return or(PathSelectors.regex("/user.*"));//这里是正则表达式
    }


    /**财务文档*/
    @Bean
    public Docket financeDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("财务文档")//分组名称
                .select()
                .paths(financePaths())//指定路径处理PathSelectors.any()代表所有的
                .build()
                .apiInfo(apiInfo());
    }
    @SuppressWarnings("unchecked")
    private Predicate<String> financePaths() {
        return or(PathSelectors.regex("/finance.*"));//这里是正则表达式
    }


    /**指定了页面显示的信息，标题、描述*/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("使用Spring Boot 集成 swagger")
                .description("玩转Spring Boot 博客地址：https://blog.youkuaiyun.com/LTY1998").build();
    }

}

具体里面的功能已经通过注解写的比较清楚了，但是在我根据教程搭建的时候只是搭建了user/里面的方法。
首先要创建一个实体类，然后将参数进行配置

package com.example.swagger.bean;



public class User {
    private Long id;
    private String name;
    private String sex;
    private Integer age;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "User [id=" + id + ", name=" + name + ", sex=" + sex + ", age=" + age + "]";
    }

}

然后在contol里面进行配置 ，然后就可以在网页上直接进行测试了

package com.example.swagger.controller;

import com.example.swagger.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.List;



@RestController
@RequestMapping("/user")
@Api(tags = "user")
public class UserController {
    public List<User> getUserList() {
        return null;
    }


    /**
     *
     * @param user
     * @return
     */
    @ApiOperation("增加用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "name", dataType = "String", required = true, value = "姓名", defaultValue = "李天宇"),
            @ApiImplicitParam(paramType = "query", name = "sex", dataType = "String", required = true, value = "性别", defaultValue = "男"),
            @ApiImplicitParam(paramType = "query", name = "age", dataType = "int", required = false, value = "年龄", defaultValue = "18") })
    @RequestMapping(method = RequestMethod.POST)
    public User save(User user) {
        // 这里为了方便直接将输入内容返回
        return user;
    }

    /**
     *
     * @param id
     * @param user
     * @return
     */
    @ApiOperation(value = "修改用户信息", notes = "根据ID修改用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(paramType = "body", name = "user", value = "用户实体", required = true, dataType = "User") })
    @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
    public User update(@PathVariable Long id, @RequestBody User user) {
        // 这里为了方便直接将输入内容返回
        return user;
    }
}

 

最后新建一个model类对返回的信息的处理

package com.reset.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;


@ApiModel(description = "返回响应数据")
public class RestMessgae {

    @ApiModelProperty(value = "错误信息")
    private String message;
    @ApiModelProperty(value = "状态码")
    private String code;
    @ApiModelProperty(value = "返回的数据")
    private Object data;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }
}

Swagger里面常用注解介绍

@Api()：作用于类上，表示这个类是swagger的资源。
tags = ”说明该类的作用“
@ApiOperation()：用在请求的方法上，说明的方法的用户和作用
value=“说明方法的用途、作用”
notes="方法的备注说明“
@ApiImplicitParams()：用在请求的方法上，表示一组参数说明，可以包含多个@ApiImplicitParam()
@ApiImplicitParam()：指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明
required：参数是否必须传
dataType：参数类型
defaultValue：参数的默认值
@ApiResponses()：用在请求的方法上，表示一组响应。可以包含多个@ApiResponse()
@ApiResponse()：用于表示一个错误的响应信息
code：数字
message：信息
response：抛出异常的类