Knife4j
基本介绍
Knife4j是一款基于Swagger 2的在线API文档框架。
基本使用
在项目中添加依赖
<!-- Knife4j Spring Boot:在线API --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>
注意:以上依赖项仅适用于Spring Boot 2.6(不含)之前的版本。
在配置文件中开启增强模式
在application.properties
中添加:
knife4j.enable=true
自定义配置类,实现必要的配置
在cn.tedu.csmall.server.config
包下创建Knife4jConfiguration
,并添加配置:
提示:以下配置代码是相对固定的。
@Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { /** * 【重要】指定Controller包路径 */ private String basePackage = "cn.tedu.csmall.server.controller"; /** * 分组名称 */ private String groupName = "product"; /** * 主机名 */ private String host = "http://java.tedu.cn"; /** * 标题 */ private String title = "酷鲨商城在线API文档--商品管理"; /** * 简介 */ private String description = "酷鲨商城在线API文档--商品管理"; /** * 服务条款URL */ private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0"; /** * 联系人 */ private String contactName = "Java教学研发部"; /** * 联系网址 */ private String contactUrl = "http://java.tedu.cn"; /** * 联系邮箱 */ private String contactEmail = "java@tedu.cn"; /** * 版本号 */ private String version = "1.0.0"; @Autowired private OpenApiExtensionResolver openApiExtensionResolver; @Bean public Docket docket() { String groupName = "1.0.0"; Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(host) .apiInfo(apiInfo()) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(basePackage)) .paths(PathSelectors.any()) .build() .extensions(openApiExtensionResolver.buildExtensions(groupName)); return docket; } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(title) .description(description) .termsOfServiceUrl(termsOfServiceUrl) .contact(new Contact(contactName, contactUrl, contactEmail)) .version(version) .build(); } }
使用
打开浏览器,输入 http://localhost:8080/doc.html 即可访问。
详细配置
-
在控制器类上添加
@Api
注解,配置tags
属性,可以指定模块名称(API文档中的一级菜单中显示的名称) -
在处理请求的方法上添加
@ApiOperation
注解,配置value
属性,可以指定业务名称(API文档中的一级菜单的子项显示的名称) -
在处理请求的方法上添加
@ApiOperationSupport
注解,配置order
属性,取值为数值,可以指定业务的显示排序序号,将根据order
属性值升序排列 -
在处理请求的方法的POJO参数的属性上添加
@ApiModelProperty
注解,配置value
属性,可以指定参数的说明,另外,还可以通过此注解的required
属性配置此参数是否必须(并不具备检查功能,只是在API文档上显示为必须提交)