一 引入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
效果图如下：
四 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@ApiModelpublic 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]"
具体查看源码：
/**
* 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注解失效。
此文章纯属学习笔记，如有什么不足之处请在下方留言，我一会竭力改进
原文地址：https://www.cnblogs.com/xifenglou/p/12692211.html