Springboot中整合knife4j接口文档
在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发。
什么是knife4j
简单说knife4j就swagger的升级版API文档的一个框架,但是用起来比swagger方便多了,UI更加丰富。
界面欣赏
主页
接口文档
调试界面
参数实体
整合 knife4j
引入 maven 依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索3.X最新版本号-->
<version>3.0.3</version>
</dependency>
knife4j 配置文件
创建 Knife4jConfig 文件
package com.didiplus.common.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* Author: didiplus
* Email: 972479352@qq.com
* CreateTime: 2022/4/25
* Desc: knife4j 配置
*/
@Configuration
@EnableKnife4j
public class Knife4jConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.didiplus"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot项目 后台服务API接口文档")
.description("使用 knife4j 搭建的后台服务API接口文档")
.termsOfServiceUrl("http://localhost:8080/")
.contact("didiplus")
.version("1.0.0")
.build();
}
}
配置API接口
package com.didiplus.modules.sys.controller;
import com.didiplus.modules.sys.domain.SysDictType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Author: didiplus
* Email: 972479352@qq.com
* CreateTime: 2022/4/25
* Desc: 数据字典控制器
*/
@RestController
@Api(tags = "数据字典")
@RequestMapping("/api/sys/dictType")
public class SysDictTypeController {
@ApiOperation("添加")
@PostMapping("/add")
public SysDictType add() {
SysDictType dictType = new SysDictType();
dictType.setId("1");
dictType.setTypeName("用户状态");
dictType.setTypeCode("user_type");
dictType.setDescription("用户状态");
dictType.setEnable("true");
return dictType;
}
}
通过 @Api
注解标注需要生成接口文档,通过 @ApiOperation
注解标注接口名。 同时我们给 SysDictType
也加上对应的注解
package com.didiplus.modules.sys.domain;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotEmpty;
/**
* Author: didiplus
* Email: 972479352@qq.com
* CreateTime: 2022/4/25
* Desc: 字典类型领域模型
*/
@Data
@ApiModel(value = "字典类型")
public class SysDictType {
@ApiModelProperty("ID")
private String id;
@NotEmpty(message = "字典编码不能为空")
@ApiModelProperty(name = "字典名称",example = "用户ID")
private String typeName;
@NotEmpty(message = "字典编码不能为空")
@ApiModelProperty(value = "字典编码")
private String typeCode;
@ApiModelProperty(value = "字典描述")
private String description;
@NotEmpty(message = "字典状态不能为空")
@ApiModelProperty(value = "字典状态")
private String enable;
}
通过 @ApiModel
标注这是一个参数实体,通过 @ApiModelProperty
标注字段说明。
访问 http://localhost:8080/doc.html体验一下,出现访问资源异常
出现这个问题的原因是因为我们加上了 ResponseBodyAdvice
统一处理返回值/响应体,导致给Swagger的返回值也包装了一层,UI页面无法解析。可以通过 http://localhost:8080/v2/api-docs?group=SwaggerDemo观察Swagger返回的json数据。
既然知道了问题原因那就很好解决了,我们只需要在ResponseBodyAdvice
处理类中只转换我们自己项目的接口即可。
@RestControllerAdvice(basePackages = "com.didiplus.modules")
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
....省略....
}
详细的可以参考SpringBoot 如何统一后端返回格式。通过添加basePackage
属性限定统一返回值的范围,这样就不影Swagger
了 ,重启服务器再次访问swagger
接口地址,就可以看到接口文档页面了。
knife4j 常用特性
knife4j 在 swagger 的基础上做了许多增强,这里介绍几个最常用的。使用增强特性需在application.yml
中开启 。
knife4j:
production: false
enable: true
全局参数
前后端分离开发中一般使用 token 作为请求参数进行身份与权限鉴定,有放在 query(表单)和 header(请求头)的,knife4j 对这两种都进行了支持,只需在侧边栏‘文档管理 -> 全局参数设置’中设置。
离线文档
有时我们需要一份离线文档可以随时随地进行查看,knife4j 支持导出四种格式( md、html、doc 、json)的离线文档,在侧边栏‘文档管理 -> 离线文档’中导出。
Springboot中整合knife4j接口文档的更多相关文章
- Abp中SwaggerUI的接口文档添加上传文件参数类型
在使用Swashbuckle上传文件的时候,在接口文档中希望看到上传控件,但是C#中,没有FromBodyAttribute这个特性,所以需要在运行时,修改参数的swagger属性. 首先看下,最 ...
- Springboot集成swagger2生成接口文档
[转载请注明]: 原文出处:https://www.cnblogs.com/jstarseven/p/11509884.html 作者:jstarseven 码字挺辛苦的..... 一 ...
- springboot结合swagger生成接口文档
原文链接:https://www.cnblogs.com/xu-lei/p/7423883.html https://www.jianshu.com/p/b9ae3136b292 前后台分离的开发渐渐 ...
- 【转】springboot结合swagger生成接口文档
前后台分离的开发渐渐已成趋势.那么前后端的沟通就成了问题,包括移动端,web端.如果有一个东西在我们写完代码的时候,自动将接口的所有注释,调用文档提供出来,是不是一件很美好的事情.那就是使用swagg ...
- springboot+swagger接口文档企业实践(上)
目录 1.引言 2.swagger简介 2.1 swagger 介绍 2.2 springfox.swagger与springboot 3. 使用springboot+swagger构建接口文档 3. ...
- SpringBoot整合knife4j框架(可生成离线接口文档),并设置接口请求头token默认值
功能和swagger类似 官网地址:https://doc.xiaominfo.com/knife4j/ 这个框架可以设置返回字段的描述 引入依赖 <dependency> <gro ...
- SpringBoot整合Swagger2,再也不用维护接口文档了!
前后端分离后,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很 ...
- 如何让接口文档自动生成,SpringBoot中Swagger的使用
目录 一.在SpringBoot项目中配置Swagger2 1.pom.xml中对Swagger2的依赖 2.编写配置类启用Swagger 3.配置实体类的文档 4.配置接口的文档 5.访问文档 二. ...
- SpringBoot(六) SpringBoot整合Swagger2(自动化生成接口文档)
一:在上篇文章pom增加依赖: <dependency> <groupId>io.springfox</groupId> <artifactId>spr ...
随机推荐
- Java9的模块化是什么
Java9新特性中的模块化到底是什么 Java9中的一个重大特性是增加了一种新型的程序设计组件 - 模块. 官方对模块的定义为:一个被命名的,代码和数据的自描述集合.( the module, whi ...
- 【编程教室】PONG - 100行代码写一个弹球游戏
大家好,欢迎来到 Crossin的编程教室 ! 今天跟大家讲一讲:如何做游戏 游戏的主题是弹球游戏<PONG>,它是史上第一款街机游戏.因此选它作为我这个游戏开发系列的第一期主题. 游戏引 ...
- TTL、RS232、RS485、UART、串口的关系和常见半双工、全双工协议
串口(UART口).COM口.USB口.DB9.DB25是指的物理接口形式(硬件) TTL.RS-232.RS-485是指的电平标准(电平信号) 我们单片机嵌入式常用的串口有三种(TTL/RS-2 ...
- MVCC多版本并发控制
MVCC多版本并发控制 爱情小傻蛋关注 82019.09.28 23:23:37字数 4,740阅读 91,421 前提概要 什么是MVCC 什么是当前读和快照读? 当前读,快照读和MVCC的关系 M ...
- 重写hashcode和equals方法
重写hashcode和equals方法 简乐君 2019-05-07 21:55:43 35481 收藏 191分类专栏: Java 文章标签: equals() hashcode()版权 一.前言我 ...
- 如何在不使用BasePACKAGE过滤器的情况下排除程序包?
过滤程序包的方法不尽相同.但是弹簧启动提供了一个更复杂的选项,可以在不接触组件扫描的情况下实现这一点. 在使用注释@ SpringBootApplication时,可以使用排除属性. 请参阅下面的代码 ...
- 学习zabbix(三)
前言: 学习zabbix之前,不得不了解的是SNMP协议 SNMP:简单网络管理协议(Simple Network Protocol) Snmp由两部分组成,监控端和被监控端 监控模式: 主动模式:N ...
- 12 Web Development Trends That Will Dominate 2022
12 Web Development Trends That Will Dominate 2022 (mindinventory.com) Progressive Web Apps (PWAs) An ...
- php 实验一 网页设计
实验目的: 1. 能够对整个页面进行html结构设计. 2. 掌握CSS+DIV的应用. 实验内容及要求: ***个人博客网页 参考Internet网上的博客网站,设计自己的个人网页,主要包括:图 ...
- HTML表格CSS美化
效果展示 style.css html{ width: 100%; height: 100%; overflow: hidden;}body{ width: 100%; height: 100%; f ...