Java-swagger
效果图 :
环境配置 :
1> pom.xml :
io.springfox
springfox-swagger2
2.2.2
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger2
2.9.2
io.swagger
swagger-annotations
io.swagger
swagger-models
io.springfox
springfox-swagger-ui
2.9.2
io.swagger
swagger-annotations
1.5.21
io.swagger
swagger-models
1.5.21
com.github.xiaoymin
swagger-bootstrap-ui
1.9.3
2> application.properties :
# 需要swagger扫描的包
swagger.basepackage=
# 项目分组
swagger.group=
# 项目标题
swagger.title=
# 项目描述
swagger.description=
# 项目版本
swagger.version=1.0.0
# 服务访问地址
swagger.termsOfServiceUrl=
# 联系人
swagger.contact=urn:tos
# 根路径
swagger.basepath=/v1
swagger.license=LICENSE-2.0
swagger.licenseUrl=http://www.apache.org/licenses/LICENSE-2.0
# 是否展示
swagger.show=true
3> 项目配置 SwaggerConfig.java
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* swagger配置
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${swagger.group:bigtreefinance}")
private String group;
@Value("${swagger.title:未设置项目标题}")
private String title;
@Value("${swagger.description:未设置项目描述}")
private String description;
@Value("${swagger.version:未设置版本号}")
private String version;
@Value("${swagger.termsOfServiceUrl:未设置服务地址}")
private String termsOfServiceUrl;
@Value("${swagger.contact:未设置联系人}")
private String contact;
// 可以取server.servlet.context-path
@Value("${swagger.basepath:/}")
private String basepath;
@Value("${swagger.basepackage:com}")
private String basepackage;
@Value("${swagger.show:true}")
private String show;
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(show)
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping(basepath)
.select()
.apis(RequestHandlerSelectors.basePackage(basepackage))
.build()
.apiInfo(productApiInfo());
}
private ApiInfo productApiInfo() {
ApiInfo apiInfo = new ApiInfo(title, description, version, termsOfServiceUrl, contact, "LICENSE-2.0", "http://www.apache.org/licenses/LICENSE-2.0");
return apiInfo;
}
}
5> 配置过滤器
/doc.html,/v2/api-docs,/v2/api-docs-ext,/webjars/**,/swagger-resources
6> swagger注解相关
@RestController
/**
* produces : For example, "application/json, application/xml" , 可选
* consumes : For example, "application/json, application/xml" , 可选
* tags : 类接口所属业务[正常应与此类下的接口方法配置一致],接口文档会依据tags进行分组展示 , 必填
*/
@Api(produces = "application/json",consumes = "application/json",tags = "订单服务")
public class SwaggerWeb {
private static final String TAGS = "订单服务";
/**
* 订单新增 : 传递实体Bean通过@ApiParam进行注解
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS, value = "订单新增", notes = "订单新增:新增订单接口", hidden = false, response = ResponseEntity.class)
@PostMapping(value = "/order")
/**
* @ApiParam 作用与实体Bean,无需配置name和value.会依据实体Bean配置进行注解.
* hidden : 是否隐藏参数
* required : 是否必填
*/
public ResponseEntity add(@ApiParam(hidden = false,required = false) @RequestBody @Valid ReqEntity reqEntity) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(reqEntity.toString()));
}
/**
* 订单删除 : 传递非实体Bean使用@ApiImplicitParams进行注解
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS, value = "订单删除", notes = "订单删除:通过自增ID删除订单.", hidden = false, response = ResponseEntity.class)
@ApiImplicitParams({
/**
* 注解说明 : 参考订单查询
*/
@ApiImplicitParam(name = "id", value = "自增ID", example = "1",required = true)
})
@DeleteMapping(value = "/order/{id}")
public ResponseEntity delete(@PathVariable("id") String id) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(id));
}
/**
* 订单修改 : 传递实体Bean与Path
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS, value = "订单修改", notes = "订单修改:通过自增ID进行修改", hidden = false, response = ResponseEntity.class)
@ApiImplicitParams({
/**
* 注解说明 : 参考订单查询
*/
@ApiImplicitParam(name = "id", value = "自增ID", example = "1",required = true)
})
@PostMapping(value = "/order/{id}")
/**
* @ApiParam 作用与实体Bean,无需配置name和value.会依据实体Bean配置进行注解.
* hidden : 是否隐藏参数
* required : 是否必填
*/
public ResponseEntity update(@PathVariable("id") String id,@ApiParam(hidden = false,required = false) @RequestBody @Valid ReqEntity reqEntity) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(id,reqEntity.toString()));
}
/**
* 订单查询 : 传递非实体Bean使用@ApiImplicitParams进行注解
* tags : 接口所属业务组,接口文档会依据tags进行分组展示 , 如果与类的tags一致,可不填
* value : 接口名称 , 必填
* notes : 接口描述 , 可选
* hidden : 是否隐藏,默认false , 可选
* response : 返回的对象 , 必填
*/
@ApiOperation(tags = TAGS, value = "订单查询", notes = "订单查询:通过订单编号和订单名称进行查询", hidden = false, response = ResponseEntity.class)
@ApiImplicitParams({
/**
* name : 参数名称[需与方法中名称一致] , 必填
* vale : 参数说明 , 必填
* required : 是否必填 , 可选
* example : 样例 , 可选
*/
@ApiImplicitParam(name = "orderNo", value = "订单编号", example = "DDBH1130730655556190208",required = false),
@ApiImplicitParam(name = "orderName", value = "订单名称", example = "销售单")
})
@GetMapping(value = "/order")
public ResponseEntity get(String orderNo,String orderName) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(orderNo,orderName));
}
/**
* 文件上传
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS,value = "文件上传", notes = "文件上传[选择文件进行上传]",hidden = false,response = ResponseEntity.class)
@ApiImplicitParams({
/**
* 注解说明 : 参考订单查询
*/
@ApiImplicitParam(name = "col1",value = "字段1",example = "c1",required = true)
})
@PostMapping(value = "/file")
public Object file(String col1,@ApiParam(value = "上传的文件",required = true)MultipartFile file
) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,file.getOriginalFilename()));
}
/**
* 传递list参数
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS,value = "list传参", notes = "传递List参数",hidden = false,response = ResponseEntity.class)
@PostMapping(value = "/list")
public Object list(@ApiParam(value = "订单列表",required = false) @RequestBody List ids) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(ids.toString()));
}
/**
* 传递list实体类参数
* 注解说明 : 参考订单查询
*/
@ApiOperation(tags = TAGS,value = "list实体类传参", notes = "传递List实体类参数",hidden = false,response = ResponseEntity.class)
@PostMapping(value = "/listBean")
public Object listBean(@ApiParam(value = "实体Bean列表",required = false) @RequestBody List ids) {
System.err.println(ids);
return new ResponseEntity(200, "SUCCESS",Arrays.asList(ids.toString()));
}
}
实体Bean swagger注解
/**
* value : Bean的Schemal,实体类首字母小写即可 , 必填
* description : Bean描述信息 , 必填
*/
@ApiModel(value = "RequestEntity",description = "订单实体类")
public class ReqEntity {
/**
* value : 参数说明 , 必填
* example : 样例, 当为Bean或者List时无需填写 , 可选
* required : 是否必填 , 可选
* hidden : 是否隐藏参数,默认为false, 可选
*/
@ApiModelProperty(value = "姓名",required = true,example = "anyf",hidden = false)
private String name;
@ApiModelProperty(value = "年龄",example = "29")
private Integer age;
// 实体Bean无需写example,依据UserEntity的swagger进行配置
@ApiModelProperty(value = "用户列表")
private List userEntitys;
@ApiModelProperty(value = "用户信息")
private UserEntity userEntity;
}
@ApiModel(value = "ResponseEntity",description = "响应参数")
public class ResponseEntity {
@ApiModelProperty(value = "响应码",required = true,example = "200")
private Integer code;
@ApiModelProperty(value = "响应描述",example = "SUCCESS")
private String message;
@ApiModelProperty(value = "响应数据")
private Object data;
}
7> 附录 : dataType 类型
int date string double float boolean byte object long date-time file biginteger bigdecimal
8> 补充说明
请求参数配置方式分两种 :
第一种 :
// 这种方式无法配置hidden
@ApiImplicitParams({ // 实体Bean无需配置
@ApiImplicitParam(name = "col1",value = "字段1",example = "v1"),
@ApiImplicitParam(name = "col2",value = "字段2",example = "v2",required = true),
@ApiImplicitParam(name = "id",value = "唯一标识",required = true,example = "1")
})
@GetMapping(value = "/order/{id}")
public Object test1(
String col1,String col2,
@ApiParam(required = false,hidden = false) @RequestBody ReqEntity reqEntity,
@PathVariable("id") String id
) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,col2,reqEntity.toString(),id));
}
第二种 :
// 这种方式dataType为body类型,无法传递非实体Bean参数
public Object test1(
@ApiParam(required = false,hidden = false,name="col1",value="字段1") String col1, // 报错
String col2,
@ApiParam(required = false,hidden = false) @RequestBody ReqEntity reqEntity // 可传
) {
return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,col2,reqEntity.toString(),id));
}