一、Swagger？

1.1 什么是 Swagger？

• 官网说法：Swagger 是一个标准和残缺的框架，用于生成、形容、调用和可视化 RESTful 格调的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的办法，参数和模型严密集成到服务器端的代码，容许 API 来始终保持同步

1.2 什么是 SpringFox？

• 官网定义为：Automated JSON API documentation for API’s built with Spring，是一个开源的 API Doc 的框架，它的前身是 swagger-springmvc，能够将咱们的 Controller 中的办法以文档的模式展示
• 下文中须要导入的几个 maven 依赖就是通过 SpringFox 整合 Swagger，以此来反对在 Spring 框架下进行应用

1.3 Swagger2 的作用

 这里指的 Swagger2 为，springfox-swagger2。通过这个依赖就可在 spring 中应用 swagger 的注解

1. 能够生成文档模式的 api，提供给不同团队
2. 不便自测，不便领导查阅
3. 无需过多冗余的 word 文档或网页文档

二、导入的 maven 依赖

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

三、自定义配置类

@Configuration
public class Swagger2Config {public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()         .apis(RequestHandlerSelectors.basePackage("com.im.controller"))// 须要生成文档所在的包
                .paths(PathSelectors.any())
                .build();}

    private ApiInfo apiInfo() {return new ApiInfoBuilder()
                .title("springboot 应用 swagger2 构建 api 文档")// 文档题目
                .description("简略优雅的 restful 格调，http://blog.csdn.net/saytime")// 形容
                .termsOfServiceUrl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();}
}

四、测试

4.1 User 实体类

@ApiModel(value = "用户实体")
@NoArgsConstructor
@AllArgsConstructor
@Getter
@Setter
@ToString
public class User {

    @JsonIgnore
    @ApiModelProperty(name = "用户车辆",dataType = "Car" ,notes = "用户车辆")
    private Car car;

    public User(Integer userId, String userName, String password, String email, String birthDate) {
        this.userId = userId;
        this.userName = userName;
        this.password = password;
        this.email = email;
        this.birthDate = birthDate;
    }

    @ApiModelProperty(name = "用户 id", dataType = "Integer", notes = "用户 id")
    private Integer userId;

    @ApiModelProperty(name = "用户名", dataType = "String", notes = "用户名")
    private String userName;

    @ApiModelProperty(name = "明码", dataType = "String", notes = "明码")
    private String password;

    @ApiModelProperty(name = "邮箱", dataType = "String", notes = "邮箱")
    private String email;

    @ApiModelProperty(name = "生日", dataType = "String", notes = "生日")
    private String birthDate;

}

PS：实体类中曾经用了 @AllArgsConstructor，但还是写了一个带参结构器，是因为笔者自测时用了 static{} 动态代码块来初始化对象，static{} 的优先级是高于注解的，所以若没有本人写带参结构器是无奈通过编译的

4.2 UserController

@RestController
@RequestMapping("/user")
@Api(value = "用户服务", description = "用户的基本操作")
public class UserController {@ApiOperation(value = "用户列表服务", notes = "查詢所有用戶的列表信息")
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    public List<User> list() {List<User> userList = new ArrayList<>();
        for (String key : DataNode.users.keySet()) {userList.add(DataNode.users.get(key));
        }
        return userList;
    }

    @ApiOperation(value ="依据用户 ID 查问用户信息",notes="依据 url 的 id 来获取用户详细信息")
    @ApiImplicitParam(name="userId",value = "用户 ID",required = true,dataType ="Integer",paramType = "path")
    @RequestMapping(value = "/findOneById/{userId}",method = RequestMethod.GET)
    public User findOneById(@PathVariable("userId") Integer userId) {for(String key: DataNode.users.keySet()) {User user = DataNode.users.get(key);
            if(user.getUserId().equals(userId)) {return user;}
        }

        return null;
    }

    @ApiOperation(value = "依据用户名获取用户信息")
    @RequestMapping(value = "/findOneUserName/{userName}",method = RequestMethod.GET)
    @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "String",paramType = "path")
    public User findOneByName(@PathVariable("userName") String userName) {for(String key: DataNode.users.keySet()) {User user = DataNode.users.get(key);
            if(userName.equals(user.getUserName())) {return user;}
        }

        return null;
    }

    @ApiOperation(value = "依据用户名获取用户信息")
    @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "userName", value = "用户名称", required = true, dataType = "String", paramType = "query")
    })
    @RequestMapping(value = "/findOneByIdAndName",method = RequestMethod.GET)
    public User findOneByIdAndName(@RequestParam String userName, @RequestParam Integer id) {for(String key: DataNode.users.keySet()) {User user = DataNode.users.get(key);
            if(user.getUserName().equals(userName) && id.equals(user.getUserId())) {return user;}
        }

        return null;
    }

    @ApiOperation(value = "依据查问条件获取用户信息")
    @RequestMapping(value = "/findOneByCondition",method = RequestMethod.GET)
    public User findOneByCondition(UserCondition userCondition) {for(String key: DataNode.users.keySet()) {User user = DataNode.users.get(key);
            if(user.getUserName().equals(userCondition.getUserName()) &&
                    user.getUserId().equals(userCondition.getUserId())) {Car car = new Car();
                car.setName("奥迪");
                user.setCar(car);
                return user;
            }
        }
        return null;
    }
}

4.3 测试样列

五、参考

• SpringFox 初体验
• 重新认识 Swagger 和 Springfox

六、最初

 若有有余，敬请斧正
虚心若愚，求知若渴