Swagger常用注解说明
1. @Api(): 用于类,表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
2. @ApiOperation(): 用于方法,表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组
3. @ApiImplicitParam(): 用于方法，表示单独的请求参数
4. @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数名称
value–参数说明
dataType–数据类型
paramType–参数类型 -- query:请求类型为Json , form :请求为表单类型
example–举例说明
required-是否必须
5. @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明 (2.2.2版本bug造成example不显示,升级到2.4.0以上即可)
hidden–隐藏
Swagger注解最佳实践举例
@Api(description = "知识分类相关接口")
@RestController
public class KnowledgeSortsApi implements Apis {
@Autowired
private IKnowledgeSortsService knowledgeSortsService;
@ApiOperation(value = "查询知识点分类", notes = "根据查询条件,分页查询知识点分类列表")
@PostMapping(ADMIN_KNOWLEDGE_SORTS_PAGE_QUERY)
public Resp<Page<KnowledgeSortsPageResult>> pageQueryList(@ApiParam(value = "分页查询条件", required = true) @RequestBody KnowledgeSortsPageDto knowledgeSortsPageDto) {
Page<KnowledgeSortsPageResult> pageResult = knowledgeSortsService.pageQueryList(knowledgeSortsPageDto);
return Resp.success(pageResult);
}
@ApiOperation(value = "知识点分类下一级树查询", notes = "根据父级id查询下一级分类树,默认查询所有分类")
@ApiImplicitParam(name = "parentId", value = "知识点分类上级Id", required = false, paramType = "form", dataType = "long", defaultValue = "1")
@GetMapping(API_KNOWLEDGE_SORTS_LIST)
public Resp<KnowledgeSortListResult> getKnowledgeSortsList(@RequestParam(required = false, defaultValue = "1") Long parentId) {
KnowledgeSortListResult knowledgeSortListResult = knowledgeSortsService.getKnowledgeSortsList(parentId);
return Resp.success(knowledgeSortListResult);
}
}
@Getter
@Setter
@ToString
public class KnowledgeSortTreeResult implements Serializable{
@ApiModelProperty(value = "知识点分类Id",required = true)
private Long id;
@ApiModelProperty(value = "知识点分类状态", required = true)
private int knowledgeSortsStatus;
@ApiModelProperty(value = "知识点分类名称", required = true)
private String knowledgeSortsName;
@ApiModelProperty(value = "知识点分类排序", required = true)
private Integer knowledgeSortsSort;
@ApiModelProperty(value = "知识点分类下一级树", required = true)
private List<KnowledgeSortTreeResult> children = Lists.newArrayList();
}
@Getter
@Setter
@ToString
public class KnowledgeSortsPageDto extends Pageable implements Serializable {
@Comment("分类id")
@ApiModelProperty(value = "知识点分类Id", required = false, example = "2")
private Long knowledgeSortsId;
@Comment("分类编码")
@ApiModelProperty(value = "知识点分类编码", required = false, example = "")
private String knowledgeSortsCode;
@Comment("分类名称")
@ApiModelProperty(value = "知识点分类名称", required = false, example = "")
private String knowledgeSortsName;
@ApiModelProperty(value = "知识点分类状态", required = false, example = "1")
@Comment("分类状态")
private Integer knowledgeSortsStatus;
}
@Getter
@Setter
@ToString
public class KnowledgeSortsPageResult implements Serializable{
@ApiModelProperty(name = "id", value = "知识点分类Id", required = true)
private long id;
@ApiModelProperty(value = "知识点分类编码", required = true)
private String knowledgeSortsCode;
@ApiModelProperty(value = "知识点分类名称", required = true)
private String knowledgeSortsName;
@ApiModelProperty(value = "知识点分类注释", required = true)
private String knowledgeSortsRemark;
@ApiModelProperty(value = "知识点分类排序", required = true)
private int knowledgeSortsSort;
@ApiModelProperty(value = "知识点分类状态", required = true)
private int knowledgeSortsStatus;
}
Swagger配置类
package com.example.config;
/**
* Copyright © 2018年08月05日 北京自如信息科技有限公司. All rights reserved.
*
* @Prject: demo_20180801
* @Package: com.example.config
* @Description: Swagger生产配置类
* @author: Crazy4J
* @date: 2018年08月05日 12:38
* @version: V1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
//根据ApiOperation注解过滤显示的接口
Predicate<RequestHandler> predicate = requestHandler -> {
HandlerMethod handlerMethod = requestHandler.getHandlerMethod();
ApiOperation methodAnnotation = handlerMethod.getMethodAnnotation(ApiOperation.class);
if (methodAnnotation == null) {
return false;
}
String value = methodAnnotation.value();
if (value.contains(VERSION) || StringUtils.isBlank(VERSION)) {
return true;
}
return false;
};
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.groupName("WXApi-V" + VERSION).apiInfo(apiInfo())
.select()
.apis(predicate)
.paths(PathSelectors.any())
.build().globalOperationParameters(parameterBuilder());
return docket;
}
@Bean
public Docket createRestApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.groupName("WXApi").apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build().globalOperationParameters(parameterBuilder());
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("WX Doc")
.description("WX Doc")
.termsOfServiceUrl("git@code.ziroom.com:rentbackend/WX.git")
.contact("Crazy_4J@163.com")
.version("1.0")
.build();
}
public List<Parameter> parameterBuilder() {
//添加head参数
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("access-token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return pars;
}
}
// 解决2.9.2版本问题，刷新swagger-ui.html报错问题
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!--解决进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21版本-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
