SpringBoot 集成 Swageer2
添加Maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
添加配置类
package com.erp.server.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @EnableSwagger2 @Configuration public class SwaggerConfig { @Bean public Docket creatRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.erp.server.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("进销存系统") .description("这里是进销存系统的后台接口文档") //服务条款网址 .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") //联系人 .contact(new Contact("wangbo","url地址", "email地址")) .version("1.0") .build(); } }
注解使用
@Api
用在请求类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。
value：url的路径值，在UI界面上也看到，可以不用配置。
String value() default "";
tags：说明该类的作用，可以在UI界面上看到的内容
String[] tags() default {""};
produces：配置返回数据类型，例如application/json，application/xml等
String produces() default "";
consumes：配置请求头，例如application/json，application/xml等
String protocols() default "";
authorizations：高级特性认证时配置
Authorization[] authorizations() default {@Authorization("")};
hidden：默认为false，配置为true将在文档中隐藏
boolean hidden() default false;
@ApiOperation
用在请求的方法上，说明方法的用途、作用
value：说明方法的用途、作用
String value();
notes：方法的备注说明
String notes() default "";
tags：
String[] tags() default {""};
response：返回的对象
Class<?> response() default Void.class;
responseContainer：这些对象是有效的List，Set，Map，其他是无效的
String responseContainer() default "";
responseReference：
String responseReference() default "";
httpMethod：可以配置其中HTTP请求方式
String httpMethod() default "";
nickname：
String nickname() default "";
produces：配置返回数据类型，例如application/json，application/xml等
String produces() default "";
consumes：配置请求头，例如application/json，application/xml等
String consumes() default "";
protocols：
String protocols() default "";
authorizations：高级特性认证时配置
Authorization[] authorizations() default {@Authorization("")};
hidden：默认为false，配置为true将在文档中隐藏
boolean hidden() default false;
responseHeaders：配置响应头
ResponseHeader[] responseHeaders() default {@ResponseHeader( name = "", response = Void.class )};
code：HTTP的状态码，默认200
int code() default 200;
extensions：扩展属性
Extension[] extensions() default {@Extension( properties = {@ExtensionProperty( name = "", value = "" )} )};
@ApiImplicitParams
用在请求的方法上，表示一组参数说明，里面通过ApiImplicitParam配置具体参数。
public @interface ApiImplicitParams { ApiImplicitParam[] value(); }
@ApiImplicitParam
用在请求的方法上，表示单个参数说明；或者用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
String name() default "";
value：参数说明解释
String value() default "";
defaultValue：参数的默认值
String defaultValue() default "";
allowableValues：
String allowableValues() default "";
required：参数是否必传 true | false，默认false
boolean required() default false;
access：
String access() default "";
allowMultiple：
boolean allowMultiple() default false;
dataType：参数类型，默认String，只作为标志说明，不做实际验证，String和Long
String dataType() default "";
dataTypeClass：
Class<?> dataTypeClass() default Void.class;
paramType：查询参数位置
header：请求参数放置于 Header，使用@RequestHeader获取
query：请求参数放置于请求地址后边，使用@RequestParam获取
path：请求参数放置于请求地址路径中，使用@PathVariable获取
body：以流的形式提交参数，仅支持POST
form：以form表单的形式提交参数，仅支持POST
String paramType() default "";
example：
String example() default "";
examples：
Example examples() default @Example({@ExampleProperty( mediaType = "", value = "" )});
type：
String type() default "";
format：
String format() default "";
allowEmptyValue：
boolean allowEmptyValue() default false;
readOnly：
boolean readOnly() default false;
collectionFormat：
String collectionFormat() default "";
@ApiParam
public @interface ApiParam { String name() default ""; String value() default ""; String defaultValue() default ""; String allowableValues() default ""; boolean required() default false; String access() default ""; boolean allowMultiple() default false; boolean hidden() default false; String example() default ""; Example examples() default @Example({@ExampleProperty( mediaType = "", value = "" )}); String type() default ""; String format() default ""; boolean allowEmptyValue() default false; boolean readOnly() default false; String collectionFormat() default ""; }
@ApiModel
一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候，用于对类进行说明，描述一个Model的信息，表示参数用实体类接收。
public @interface ApiModel { String value() default ""; String description() default ""; Class<?> parent() default Void.class; String discriminator() default ""; Class<?>[] subTypes() default {}; String reference() default ""; }
@ApiModelProperty
注解用于方法、字段，表示对model属性的说明或者数据操作更改，配合ApiModel一起使用。
public @interface ApiModelProperty { String value() default ""; String name() default ""; String allowableValues() default ""; String access() default ""; String notes() default ""; String dataType() default ""; boolean required() default false; int position() default 0; boolean hidden() default false; String example() default ""; boolean readOnly() default false; String reference() default ""; boolean allowEmptyValue() default false; }
@ApiResponses
用在请求的方法上，表示一组响应
public @interface ApiResponses { ApiResponse[] value(); }
@ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息
public @interface ApiResponse { int code(); String message(); Class<?> response() default Void.class; String reference() default ""; ResponseHeader[] responseHeaders() default {@ResponseHeader( name = "", response = Void.class )}; String responseContainer() default ""; }
@ApiIgnore
用在Controller类或者接口方法上，表示该类或者接口被忽略，不在接口文档显示
public @interface ApiIgnore { //简要说明为何忽略此参数/操作 String value() default ""; }
问题
目前了解到的是Swagger不支持直接获取JSONObject和Map类型的参数，这种参数内部字段不可知，文档显示不出来
如果不想封装为一个Model的话可以参考下面的博客实现下，自定义一个注解。
https://blog.csdn.net/cy921107/article/details/82761575 JSONObject
https://blog.csdn.net/hellopeng1/article/details/82227942 Map
示例
package com.erp.server.controller; import com.alibaba.fastjson.JSONObject; import com.erp.server.model.User; import com.erp.server.service.TestService; import com.erp.server.utils.Constants; import com.erp.server.utils.result.ResultBuilder; import com.erp.server.utils.result.StatusCode; import io.swagger.annotations.*; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import springfox.documentation.annotations.ApiIgnore; @Api(tags = {"测试接口类"}) @RestController @RequestMapping(value = "/api/test") public class TestController { private static final Logger logger = LoggerFactory.getLogger(TestController.class); @Autowired private TestService testService; @ApiIgnore @ApiOperation(value = "测试Hello", notes = "一个测试的hello接口") @GetMapping("/hello") public String hello(){ return "Hello Spring Boot"; } @ApiOperation(value = "查询用户", notes = "根据ID查询用户") @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "integer") @GetMapping("/user/{id}") public ResultBuilder<User> user(@PathVariable("id")Integer id){ User user = testService.getUserById(id); return new ResultBuilder<User>(user, StatusCode.SUCCESS); } @ApiOperation(value = "查询用户", notes = "根据ID和姓名查询用户") @ApiImplicitParams({ @ApiImplicitParam(name = "token", value = "用户凭证", required = true, paramType = "header", dataType = "String"), @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "integer"), @ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String") }) @GetMapping("/user/id/name") public ResultBuilder<User> user1(@RequestHeader("token")String token, @RequestParam("id")Integer id, @RequestParam("name")String name){ logger.debug("token:{},id：{},name：{}", token, id, name); User user = testService.getUserById(id); return new ResultBuilder<User>(user, StatusCode.SUCCESS); } @ApiOperation(value = "添加用户", notes = "使用JSON数据添加用户") @ApiImplicitParam(name = "jsonObject", value = "用户数据", required = true, paramType = "body", examples = @Example(value = @ExampleProperty(mediaType = "application/json", value = "{'id':'','name':'','age':''}")) ) @PostMapping("/user/add/") public ResultBuilder<User> adduser(@RequestBody JSONObject jsonObject){ logger.debug(jsonObject.toJSONString()); Integer id = jsonObject.getInteger("id"); User user = testService.getUserById(id); return new ResultBuilder<User>(user, StatusCode.SUCCESS); } @ApiOperation(value = "添加用户", notes = "使用对象数据添加用户") @ApiImplicitParam(name = "user", value = "用户数据", required = true, paramType = "body", dataType = "User") @PostMapping("/user/add1/") public ResultBuilder<User> adduser1(@RequestHeader(Constants.ACCEPT_VERSION)String acceptVersion, @RequestBody User user){ return new ResultBuilder<User>(null, StatusCode.SUCCESS); } }
@Api 使用示例
属性注释
@Api 使用在接口类上
tags 说明该类的作用，可以在UI界面上看到的内容
示例代码
@Api(tags = {"版本接口类"})
@RestController
@RequestMapping("/api/version")
public class VersionController {
......
}
界面显示
@ApiOperation 和 @ApiImplicitParam 使用示例
属性注释
@ApiOperation 使用在接口方法上
value 接口名
notes 接口注释米描述
@ApiImplicitParams 表示多个参数的情况，需@ApiImplicitParam配合使用
@ApiImplicitParam 表示单个参数
name 参数
value 参数描述
required 参数是否必须，默认false
dataType 参数类型，这个一般还是别写了，经常写了导致无法使用
paramType 参数位置
header：请求参数放置于 Header，使用@RequestHeader获取
query：请求参数放置于请求地址后边，使用@RequestParam获取
path：请求参数放置于请求地址路径中，使用@PathVariable获取
body：以流的形式提交参数，仅支持POST
form：以form表单的形式提交参数，仅支持POST
示例代码
@ApiOperation(value = "采购单列表", notes = "用于查询采购单列表") @ApiImplicitParams({ @ApiImplicitParam(name = "pageNum", value = "查询的页码，默认1", required = false, paramType = "query"), @ApiImplicitParam(name = "pageSize", value = "每页显示条数，默认10", required = false, paramType = "query"), @ApiImplicitParam(name = "wareId", value = "采购ID", required = false, paramType = "query"), @ApiImplicitParam(name = "startTime", value = "开始时间，毫秒数", required = false, paramType = "query"), @ApiImplicitParam(name = "endTime", value = "结束时间，毫秒数", required = false, paramType = "query"), @ApiImplicitParam(name = "wareStatus", value = "采购单状态。-1：删除，0：正常", required = false, paramType = "query"), @ApiImplicitParam(name = "wareType", value = "采购类型：0：入库单，1：退货单", required = false, paramType = "query") }) @GetMapping("/list") public ResultBuilder getWareHouseList(@RequestHeader(Constants.VERSION_CODE)Integer versionCode, @RequestHeader(Constants.ACCESS_TOKEN)String token, @RequestParam(value = "pageNum", required = false)Integer pageNum, @RequestParam(value = "pageSize", required = false)Integer pageSize, @RequestParam(value = "wareId", required = false)String wareId, @RequestParam(value = "startTime", required = false)Long startTime, @RequestParam(value = "endTime", required = false)Long endTime, @RequestParam(value = "wareStatus", required = false)Integer wareStatus, @RequestParam(value = "wareType", required = false)Integer wareType){ return wareHouseService.getWareHouseList(pageNum, pageSize, wareId, startTime, endTime, wareStatus, wareType); }
界面显示
@ApiModel 和 @ApiModelProperty 使用示例
属性注释
@ApiModel 使用在实体类上
value 实体类名称
description 实体类描述信息
@ApiModelProperty 使用在实体类中字段上
value 字段名
required 字段是否必须，默认false
hide 字段是否隐藏，默认false
example 字段值示例
示例代码
实体类
@ApiModel(value = "软件版本", description = "这里是描述信息") public class Version { @ApiModelProperty(value = "版本", required = true, example = "1.0.0") private String version; @ApiModelProperty(value = "版本号", required = true) private Integer versionCode; @ApiModelProperty(value = "最小版本号", required = true) private Integer minVersionCode; @ApiModelProperty(value = "强制更新标志", required = true) private Integer updateForce; @ApiModelProperty(value = "更新内容") private String updateContent; @ApiModelProperty(value = "更新地址", required = true) private String updateUrl; @ApiModelProperty(hidden = true) private Date createTime; @ApiModelProperty(hidden = true) private Date updateTime; 省略set/get }
接口方法
@ApiOperation(value = "新版本检查", notes = "检查APP是否需要进行版本升级") @PostMapping("/check") public ResultBuilder versionCheck(@RequestBody Version version){
。。。
}
界面显示
Models中也会显示这个Model
