Springfox

Swagger是什么

根据官网的介绍，Swagger是一系列用于Restful API开发的工具，开源的部分包括：

• OpenAPI Specification：API规范，规定了如何描述一个系统的API
• Swagger Codegen：用于通过API规范生成服务端和客户端代码。允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档
• Swagger Editor：用来编写API规范。浏览器中编辑YAML中的OpenAPI规范并实时预览文档
• Swagger UI：用于展示API规范。HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档

非开源的部分包括：

• Swagger Hub：云服务，相当于Editor + Codegen + UI。API设计和文档，为使用OpenAPI的团队构建
• Swagger Inspector：手动测试API的工具。API测试工具，可让您验证您的API并从现有API生成OpenAPI定义
• SoapUI Pro：功能测试和安全测试的自动化工具
• LoadUI Pro：压力测试和性能测试的自动化工具

• Swagger Parser：用于解析来自Java的OpenAPI定义的独立库
• Swagger Core：与Java相关的库，用于创建，使用和使用OpenAPI定义

Springfox是什么

在大量的中文教程中，Springfox以这样的方式出现

一.添加依赖

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

第二个看起来应该是springfox封装/修改的Swagger UI，第一个应该就是Springfox本体了，但为什么artifact有个swagger2的后缀？

这就要从Springfox是什么说起了。Springfox其实是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。这就能解释那个swagger2的后缀了，这只是Springfox对Swagger的支持。

在Swagger的教程中，都会提到@Api、@ApiModel、@ApiOperation这些注解，这些注解其实不是Springfox的，而是Swagger的。springfox-swagger2这个包依赖了swagger-core这个包，而这些注解正是在这里面。但是，swagger-core这个包是只支持JAX-RS2的，并不支持常用的Spring MVC。这就是springfox-swagger的作用了，它将上面那些用于JAX-RS2的注解适配到了Spring MVC上。

除了Spring MVC外，Springfox还支持如下库

• Spring Data REST
• JSR 303，这项标准的参考实现是Hibernate Validator

二.编写配置

@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();
        ticketPar.name("openid").description("用户的openid")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build(); //header中的ticket参数非必填，传空也可以
        pars.add(ticketPar.build()); //根据每个方法名也知道当前方法在设置什么参数
        
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host("localhost:8081")// 不配的话，默认当前项目端口
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
//                .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build()
            
            //配合上面的pars在head中添加全局参数openid
            .globalOperationParameters(pars);
        
        //可以将返回的默认401 402 403状态码去除
        docket.useDefaultResponseMessages(false);
        return docket;
    }

    private ApiInfo apiInfo() {//一般只留标题，描述，版本
        return new ApiInfoBuilder().title("XXXX项目接口文档")
                //.contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "Hanstrovsky@gmail.com"))
                .description("这是用Swagger动态生成的接口文档")
                /*.termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")*/
                .version("1.0")
                .build();
    }
}

三.启动测试

启动服务，访问：http://localhost:8081/swagger-ui.html

Swagger注解的使用

上面的是swagge-ui根据接口自动生成，不够详细。如果有需要，可以通过注解自定义接口声明。

/**
 @Api：修饰整个类，描述Controller的作用
 
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiImplicitParams：多个请求参数
 	@ApiImplicitParam：一个请求参数
 @ApiResponses：HTTP响应整体描述
 	@ApiResponse：HTTP响应其中1个描述
 
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段

 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 */

注解名称	注解含义	注解使用地方	注解参数	参数含义
@EnableSwagger2	开启swagger注解	配置类上	无	无
@Api	标识swagger识别的类	Controller类上	value tags description	url的路径值 如果设置这个值、value的值会被覆盖 对api资源的描述
@ApiIgore	屏蔽显示某个Controller，开启后在swagger上不会显示	COntroller类上	value	值
@ApiOperation	标识swagger识别的方法	Controller类中的方法	value tags description basePath position produces consumes protocols authorizations hidden response responseContainer httpMethod code extensions notes	url的路径值 如果设置这个值、value的值会被覆盖 对api资源的描述 基本路径可以不配置如果配置多个Api 想改变显示顺序位置 For example，”application/json，application/xml” For example，”application/json，application/xml” Possible values:http,https,ws,wss 高级特性认证时配置 配置为true将在文档中隐藏 返回的对象 这些对象是有效的“List”，“Set”or “Map”，其他无效 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”and “PATCh” http的状态码 默认200 扩展属性 用于提示内容
@ApiImpliciParam	修饰方法中的参数	用在@ApiImplicitParams注解中对，指定一个请求参数的各个方面	param Typename value dataType required defaultValue	参数放在哪个地方 参数代表的含义 参数名称 参数类型，有String/int，无用 是否必要 参数的默认值
@ApiImpliciParams	修饰方法中的参数	用在方法上包含一组参数说明	@ApiImpliciParam	ApiImpliciParam的数组集合
@ApiResponse	修饰方法的返回值	方法上或方法的参数上	code message class	方法返回值状态码 方法返回值信息 方法返回class
@ApiResponses	响应集配置	方法上或参数上	@ApiResponse	ApiResponse的数组集合
@ApiParam	映射方法上的参数	方法的参数上	name value defaultValue allowableValues required access allowMutiple hidden example	属性名称 属性值 默认属性值 可以不配置 是否属性必填 不过多描述 默认为false 隐藏该属性 举例子
@ApiModel	用于类，表示对类进行说明，用于参数用实体类接受	类上	value description	类名（不能同名！） 描述
@ApiModelProperty	标识一个类的属性	类的字段上	value name dateType required example hidden	字段说明 重写属性名字 重写属性类型 是否必填 举例子 隐藏

例子：

@RequestMapping("/api")


@PostMapping("/people")
@ApiOperation(value = "保存人员信息")
@ApiResponses({
       @ApiResponse(code = 0, message = "保存成功"),
       @ApiResponse(code = 1, message = "保存失败")
})
public FrontResult save(
         @ApiParam(value = "保存参数", example = "")
         @RequestBody People people) {
     people.setBirthday(Timestamp.valueOf(LocalDateTime.now()));
     return new FrontResult(FrontResult.SUCCEED, "保存成功", peopleDao.save(people));
}

@Data
@ApiModel(description = "人员信息保存请求对象")
public class People {
    @ApiModelProperty(value = "人员编号")
    private Long id;
    @ApiModelProperty(value = "姓名", required = true,position = 1)
    private String name;
    @ApiModelProperty(value = "性别", required = true,position = 2)
    private String sex;
    @ApiModelProperty(value = "生日", required = true,position = 3)
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Timestamp birthday;
}

结果：

Swagger注解的滥用

在代码中的注解已经存储了大量的信息，如果再用swagger-core的注解将这些信息用另一种方式表达出来，很容易造成改了这里忘了改那里，即修改不同步。因此Springfox的开发者不推荐大家使用swagger-core的注解来描述API，认为swagger-core的注解只是补充，只能用于实现其他方法都不能实现的调整或者覆盖。例如，更应该使用Jackson的注解，而不是@ApiModelProperty；更应该使用@NotNull或者@RequestParam#required，而不是在文档里写一句此字段必填。

但是，springfox的开发者忽略了一个事实，中文开发者用swagger-core的注解更多的是用来添加中文描述，所以，该用的时候还是用吧