1.Knife4j框架

Knife4j框架是一款基于Swagger 2框架的、能够基于项目中的控制器的代码来生成在线API文档的框架，另外，此框架还有调试功能，可以向服务器端发送请求，并获取响应结果。

关于此框架，要使之能够使用，需要：

添加依赖
添加配置类
在application.properties中添加1条配置

关于依赖的代码：

<!-- Knife4j Spring Boot：在线API -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>

关于配置类：

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 = "cn.tedu.csmall.product.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";@Autowiredprivate OpenApiExtensionResolver openApiExtensionResolver;public Knife4jConfiguration() {log.debug("加载配置类：Knife4jConfiguration");}@Beanpublic 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();}}

关于application.properties中的配置：

# 开启Knife4j框架的增强模式
knife4j.enable=true

注意：

当前项目的Spring Boot版本必须是2.6以下的版本（2.6不可用）
- 如果要使用更高版本的Spring Boot，必须使用更高版本的Knife4j
在配置类中的basePackage必须是控制器类所在的包，记得需要修改

完成后，启动项目，通过 /doc.html 即可访问在线API文档。

在开发实践中，还应该对在线API文档进行细化，需要在控制器及相关类中进行一些配置：

在控制器类上添加@Api注解，配置tags属性，此属性是String类型的
在控制器类中处理请求的方法上添加@ApiOperation注解，配置value属性，此属性是String类型的
在控制器类中处理请求的方法上添加@ApiOperationSupport注解，配置order属性，此属性是int类型的
- 此属性用于排序，数据越小越靠前，不建议使用1位的数字
在控制器类中处理请求的方法上，不要再使用没有限制请求方式的@RequestMapping，建议使用@GetMapping或@PostMapping
如果处理请求的方法中，如果参数是封装的数据类型，应该在此类型的各属性上添加@ApiModelProperty注解，以配置对参数的说明
如果处理请求的方法中，如果参数并没有封装，则需要使用@ApiImplicitParams和@ApiImplicitParam这2个注解组合来配置
- 注意：一旦配置了@ApiImplicitParam，原本的提示的值会被覆盖，应该完整的配置各属性

完整的配置示例--AlbumController：

@Api(tags = "04. 相册管理模块")
@Slf4j
@RestController
@RequestMapping("/albums")
public class AlbumController {@Autowiredprivate IAlbumService albumService;public AlbumController() {log.info("创建控制器：AlbumController");}// 添加相册// http://localhost:9080/albums/add-new?name=XiaoMi&description=TestDescription&sort=69@ApiOperation("添加相册")@ApiOperationSupport(order = 100)@PostMapping("/add-new")public String addNew(@Validated AlbumAddNewDTO albumAddNewDTO) {log.debug("开始处理【添加相册】的请求：{}", albumAddNewDTO);albumService.addNew(albumAddNewDTO);return "添加相册成功！";}// http://localhost:9080/albums/9527/delete@ApiOperation("根据id删除相册")@ApiOperationSupport(order = 200)@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "相册id", dataType = "long", required = true)})@PostMapping("/{id:[0-9]+}/delete")public String delete(@PathVariable Long id) {log.debug("开始处理【删除相册】的请求：id={}", id);albumService.deleteById(id);return "删除相册成功！";}}

完整的配置示例--AlbumAddNewDTO：

@Data
public class AlbumAddNewDTO implements Serializable {/*** 相册名称*/@ApiModelProperty(value = "相册名称", example = "小米80的相册", required = true)@NotNull(message = "必须提交相册名称！")private String name;/*** 相册简介*/@ApiModelProperty(value = "相册简介", example = "小米80的相册的简介", required = true)@NotNull(message = "必须提交相册简介！")private String description;/*** 自定义排序序号*/@ApiModelProperty(value = "自定义排序序号", example = "88", required = true)@NotNull(message = "必须提交自定义排序序号！")@Range(max = 99, message = "自定义排序序号必须是0~99之间的值！")private Integer sort;}

2.关于响应结果

当服务器端向客户端响应数据时，除了必要的提示文本以外，还应该响应“业务状态码”到客户端，以便于客户端程序能够便捷且准确的判断当前请求的执行结果！

另外，某些操作是需要向客户端响应数据的

所以，向客户端的响应数据至少需要包含以下部分：

业务状态码：本质上是一个数值，由服务器端和客户端共同约定每个数值的意义
业务执行出错时的描述文本
数据：当处理请求成功时，可能需要响应某些数据到客户端（通常是客户端发起GET请求，当然，某些POST请求可能也需要响应数据）

以上做法应该是针对所有请求都是如此响应的，通常，会自定义某个类型，用于封装以上3种数据，作为处理请求的方法的返回值类型，当响应时，Spring MVC框架会将返回值转换成JSON格式的字符串！

提示：Spring MVC能够将处理请求的方法的返回值转换成JSON格式的字符串，需要：

此方法是响应正文的

此项目中需要添加jackson-databind依赖
在Spring Boot中，spring-boot-starter-web中包含了此依赖

此方法的返回值类型在Spring MVC中没有默认的Converter（转换器），会自动调用jackson-databind中的Converter，而jackson-databind的处理方法就是将返回值转换成JSON格式的字符串
只要是自定义的数据类型，在Spring MVC中都没有默认的Converter

例如，在项目的根包下创建web.JsonResult类：

@Data
public class JsonResult implements Serializable {private Integer state;private String message;private Object data;
}

以上类型，将作为项目中每个处理请求的方法、每个处理异常的方法的返回值类型！

如果在Service层始终抛出ServiceException，由于使用了统一处理异常的机制，会导致所有异常的业务状态码都是相同的！为了解决此问题，可以：

创建多种异常类型，针对不同的错误，在Service层抛出不同的异常
在Service层每次抛出异常时，向异常对象中封装业务状态码

如果采取以上第2种做法，则需要将ServiceException调整为：

@Getter
public class ServiceException extends RuntimeException {private Integer state;public ServiceException(Integer state, String message) {super(message);this.state = state;}}

然后，另外自定义一个接口，用于声明各业务状态码的常量：

public interface ServiceCode {Integer ERR_CONFLICT = 2;Integer ERR_NOT_FOUND = 6;Integer ERR_INSERT = 3;Integer ERR_UPDATE = 4;Integer ERR_DELETE = 5;}

并且，在抛出异常时，向异常对象中封装以上业务状态码，例如：

String message = "添加相册失败！相册名称【" + name + "】已存在！";
log.warn(message);
throw new ServiceException(ServiceCode.ERR_CONFLICT, message);

this.axios.post(url, data).then(() => {let data = response.data;if (data.state == 1) {// 成功} else if (data.state == 2) {// 显示 data.message}
});

JSD-2204-Knife4j框架-处理响应结果-Day07相关推荐

SpringBoot整合Knife4j框架
相关简化代码的Lombok(跳转) 文章目录一.Knife4j 二.环境准备 1.引入依赖 2.添加配置 3.设置配置类 4.运行访问三.基本用法 1.控制器 2.封装类四.效果演示五.其它 ...
使用Bootstrap框架-实现响应式页面开源案例-阿里百秀静态页面
使用Bootstrap框架-实现响应式页面开源案例-阿里百秀静态页面 tips 在不同设备中显示的样式页面布局思路 html css tips 这个页面里的图片忒难看,实际可以换一换在不同设备中显 ...
Bootstrap 前端框架制作响应式网站
放假突然兴起,想学点前端框架,制作一个页面玩玩(PS:一直做后端,怕忘了前端的知识,所以补一补).说做就做,花了一天的时间,谷歌开发者模式,仿制别人公司的页面(希望不会被查),做了个响应式小网页,可以 ...
java官网门户源码 SSM框架自适应-响应式 freemarker 静态模版引擎
来源:http://www.fhadmin.org/webnewsdetail3.html 前台:支持(5+1[时尚单页风格])六套模版,可以在后台切换官网:www.fhadmin.org 系统介绍 ...
Popular MVC框架请求响应数据加解密@Decrypt和@Encrypt的使用示例
简介此项目用于演示popularmvc如何提供统一全自动化的API隐私数据保护,并且可以做到业务无感和灵活指定数据加解密算法. 请求数据加密使用@Decrypt注解,响应信息加密使用@Encrypt ...
layui框架的响应式布局
关于layui框架响应式布局的一些使用方法写在前面的因为公司的需要,这几天学习了layui框架,稍微有一些心得.介绍就不多说,贴上官网的说明文档,目前是2.0版本,上面有很详细的介绍. 官网地址: ...
Vue框架设置响应式布局
最近折腾自己的网站,在自适应方面发现有了很多新的方法,感叹前端的技术真是日新月异,从以前只能这样,到现在除了这样,还可以那样,甚至再那样......技术永无止境啊. 回到主题,自适应响应式布局这个话题 ...
go 框架iris 响应记录器
iris go 语言 iris 是一个强大的框架,写一个http 服务是比较方便的,记录他收到的所有参数,方法等等也是有必要的, 使用logger来记录,以便于调试和发现错误,因为在测试没有充分的情况 ...
第四阶段product笔记
文章目录第一天关于此项目项目的开发流程关于数据库与数据表具体开发顺序实现数据访问层的开发第二天 LOMBOK Mybatis框架 Mybatis框架的主要作用使用Mybatis的前期准 ...

JSD-2204-Knife4j框架-处理响应结果-Day07

1.Knife4j框架

2.关于响应结果

JSD-2204-Knife4j框架-处理响应结果-Day07相关推荐

最新文章

热门文章