作用:
用来记录显示后端有几个Controller控制器业务,每一个业务里面有多少个业务功能(就是处理业务的方法,客户端和服务端的每次交互都由这个处理业务的方法来接收请求和相应结果),还可以在这个文档中对每个业务方法发送他所需要的参数数据,进行测试前端和后端的连接是否有问题,还可以看到服务端响应之后的结果都是什么;
添加Knif4j的三个步骤
1.先在pom.xml文件中添加这个框架的依赖,将这个框架的jar包带入进自己的本地仓库里面,
这个我上传了相关依赖:
<!-- Knife4j Spring Boot:在线API -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
注:这个框架只能用在Springboot框架的2.6以下的版本,不包括2.6版本;
2.在application.properties配置文件中开启Knife4j框架的增强模式:
#激活knife4jAPI在线文档
knife4j.enable=true
3.在工程的配置类包中添加Knife4j的配置类,在这里添加这个配置类相当于可以全局监控controller层业务模块和里面的处理业务的方法,因为这个框架是固定的模式,所以每个API文档都是一样的,代码也是一样的,就改一下里面的一些基本信息就行了(根据自己的实际情况做改变):
package cn.tedu.csmall.product.config;//将此处的包名改为你自己项目的包名路径
//将下面双引号中带X的改为自己的项目信息即可
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
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.EnableSwagger2WebMvc;
/**
* Knife4j配置类
*
* @author java@tedu.cn
* @version 0.0.1
*/
@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {//将这个包名改为自己所需要的包名
/**
* 【重要】指定Controller包路径
*/
private String basePackage = "XXX";
/**
* 分组名称
*/
private String groupName = "XXX";
/**
* 主机名
*/
private String host = "XXX";
/**
* 标题
*/
private String title = "XXX";
/**
* 简介
*/
private String description = "XXX";
/**
* 服务条款URL
*/
private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
/**
* 联系人
*/
private String contactName = "XXX";
/**
* 联系网址
*/
private String contactUrl = "XXX";
/**
* 联系邮箱
*/
private String contactEmail = "XXX";
/**
* 版本号
*/
private String version = "1.0.0";
@Autowired
private OpenApiExtensionResolver openApiExtensionResolver;
public Knife4jConfiguration() {
log.debug("创建配置类对象:Knife4jConfiguration");
}
@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在线文档,如图:
以上是这个框架的基本实现内容;
框架的注解:
1.@Api注解,这个注解可以设置里面的tage这个属性的值来给Controller设置名称(作用在类上面),在设置的名称之后加个前缀可以根据你给的前缀排序,例如(1,2,3,4/a,b,c,d);
2.@ApiOperation注解,这个注解可以通过设置里面 的value这个属性的值来设置处理业务的方法的名称(作用在方法上);
3.@ApiOperationSupper注解,这个注解可以通过设置里面的order这个属性的值来对所有的方法进行排序,这个只能设置Integer值;
4.@ApiModelProperty注解:这个注解作用在客户端传过来的类属性上面(DTO类),他里面value属性可以设置属性的昵称,required这个属性可以设置这个前端是否必须提交此属性,example属性可以显示属性的显例值;
5.@ApiImplicitParam注解,这个注解作用在处理业务的方法上面,主要是对那些没有被封装的属性;
- 必须配置此注解的`name`属性,取值为方法的参数名称,表示当前注解对哪个参数进行说明
- 此注解的`value`属性,可配置参数名称(说明)
- 此注解的`required`属性,可配置是否必须提交此参数
- 此注解的`dataType`属性,可配置参数的数据类型(例如取值为`"long"`)
- 此注解的`example`属性,可配置此请求参数的示例值
后端代码图:
在线文档显示图:
这样就可以一边写后端一边就可以进行测试,还可以进行记录,和前端交接的时候只要这个在线API文档就可以了;