Springfox集成Swagger2实战篇

一引入maven依赖

compile 'io.springfox:springfox-swagger2:2.9.2'
compile 'io.springfox:springfox-swagger-ui:2.9.2'
compile "io.springfox:springfox-bean-validators:2.9.2"

二 编写配置文件

package com.wxbc.constant;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2 {
    @Bean
    public Docket createRestApi() {

         return new Docket(DocumentationType.SWAGGER_2)
         .select()
         .apis(RequestHandlerSelectors.any())
         .paths(PathSelectors.any())
         .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("test平台端").description("可以直接访问的接口")
                .version("0.1")
                .build();
    }

}

三启动项目访问http://localhost:9079/swagger-ui.html

效果图如下：

Springfox集成Swagger2实战篇

四 Swagger2常用注解介绍

常用注解：
- @Api()用于类；
表示标识这个类是swagger的资源 , 一般作用于Controller上

@Api(tags = "(查询类api)")

- @ApiOperation()用于方法；
表示一个http请求的操作，一般作用于接收http请示的方法上
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收，一般作用于@RequestBody的类上

- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改

- @ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiOperation(value = "test", notes = "test2",
        response = Response.class)
@PostMapping("/query")
public Response queryTransferDetail(@Valid @RequestBody QueryDetailPara para) throws ParameterException {

    return Response.success();
}

@ApiModel()用于类；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–是否对前端隐藏

@Data
@ApiModel
public class QueryDetailPara extends BaseInfo {

    @NotBlank(message = "project不能为空")
    @ApiModelProperty(value = "项目来源",required = true,example = "rhine3")
    @Size(min = 1,max = 65)
    private String project;

    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用户年龄",allowableValues = "range[1,11]")
    private Integer age;

    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用户年龄")
    private Integer age1;


    @Max(100)
    @Min(10)
    @ApiModelProperty(value = "用户年龄",allowableValues = "10,100,1000")
    private Integer age2;

}

JSR 303：Bean Validation 允许您注释Java类的字段以声明约束和验证规则。您可以使用以下规则注释单个字段： - 不能为空，最小值，最大值，正则表达式匹配等。

一点说明：

1. @Max @Min注解只能作用于Integer类的整形约束

2. 如果要修释字符串的长度，使用@Size注解

3.如果有些数据项需要枚举值，可使用allowableValues,有三种写法，

i) allowableValues="test1,test2,test3"

ii) allowableValues="range[1,11]"

iii) allowableValues="range[1,infinity]"

具体查看源码：

 /**
     * Limits the acceptable values for this parameter.
     * <p>
     * There are three ways to describe the allowable values:
     * <ol>
     * <li>To set a list of values, provide a comma-separated list.
     * For example: {@code first, second, third}.</li>
     * <li>To set a range of values, start the value with "range", and surrounding by square
     * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
     * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
     * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
     * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
     * minimum allowable value of this parameter is 1.</li>
     * </ol>
     */
    String allowableValues() default "";

4. 使用allowableValues属性会导致@Max @Min及@Size注解失效。

此文章纯属学习笔记，如有什么不足之处请在下方留言，我一会竭力改进

Springfox集成Swagger2实战篇

相关推荐