Spring Boot +swagger2

pom.xml导入插件

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

Config 配置文件

package com.uservice.Config;

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;

/**
 * Created by pudding on 2017-9-12.(YYR)
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.uservice.Controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("账户权限接口")
                //创建人
                .contact("YYR")
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

实体注解示例

package com.uservice.Dto;

import com.uservice.MybatisUtil.Invisible;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.Date;


/**
 * Created by pudding on 2017-8-24.（YYR）
 */
@ApiModel("User(账户模型)")
@Data
public class User {

    @ApiModelProperty("ID")
    Integer id;

    @ApiModelProperty("登录账号")
    String username;

    @ApiModelProperty("密码")
    String password;

    @ApiModelProperty("名字拼音")
    String name;

    @ApiModelProperty("工号")
    String job;

    @ApiModelProperty("真实姓名")
    String vsername;

    @ApiModelProperty("电话")
    String mobile;

    @ApiModelProperty("email")
    String email;

    @ApiModelProperty("注册时间")
    Date add_time;

    @ApiModelProperty("第一次登录时间")
    Date login_time;

    @ApiModelProperty("最后一次登录时间")
    Date last_login_time;

    @ApiModelProperty("登录次数")
    int count;

    @ApiModelProperty("角色名称")
    @Invisible
    String role_name;

    @ApiModelProperty("组名称")
    @Invisible
    String group_name;

    @ApiModelProperty("部门名称")
    @Invisible
    String deptname;

}

@RestController
@RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
public class UserController {

    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

}

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html