网站建设与维护的工资,中国能源建设集团网站,重庆做企业年报在哪个网站做,旅游网站建设期集成 Knife4j 前言Knife4j是什么集成 Knife4j引入 pom 依赖添加基础配置启动程序测试完善文档信息编写配置类修改 UserController修改 UserEntity修改 BaseEntity 文档效果图swagger 界面knife4j 界面 前言
前面一小节我们使用postman来进行接口的调试#xff0c;如果接口一多… 集成 Knife4j 前言Knife4j是什么集成 Knife4j引入 pom 依赖添加基础配置启动程序测试完善文档信息编写配置类修改 UserController修改 UserEntity修改 BaseEntity 文档效果图swagger 界面knife4j 界面 前言
前面一小节我们使用postman来进行接口的调试如果接口一多就很不方便进行管理也不方便调试所以我们本小节集成一个接口文档组件Knife4j有疑问可以查看 Knife4j 官网。
Knife4j是什么
Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案
Knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案前身是 swagger-bootstrap-ui致力于 springfox-swagger 的增强 UI 实现。knife4j 为了契合微服务的架构发展由于原来 swagger-bootstrap-ui 采用的是后端 Java 代码 前端 UI 混合打包的方式在微服务架构下显的很臃肿因此项目正式更名为 knife4j更名后主要专注的方面如下
后端 Java 代码以及前端 UI 模块进行了分离在微服务架构下使用更加灵活提供专注于 Swagger 的增强解决方案不同于只是单纯增强前端 UI 部分
集成 Knife4j
我们参考 Knife4j 官网的教程进行集成。 因为我们的 Spring Boot 版本是 3.2.0所以只支持 OpenAPI3 规范 Spring Boot 3 只支持OpenAPI3规范Knife4j提供的starter已经引用springdoc-openapi的jar开发者需注意避免jar包冲突 引入 pom 依赖
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.3.0/version
/dependency添加基础配置
引入之后其余的配置开发者即可完全参考springdoc-openapi的项目说明Knife4j只提供了增强部分如果要启用Knife4j的增强功能可以在配置文件中进行开启
官网提供的部分配置如下我们修改一下相关信息
# springdoc-openapi项目配置
springdoc:swagger-ui:# swagger ui 路径path: /swagger-ui.html# 排序方式 alpha 按字母顺序tags-sorter: alphaoperations-sorter: alphaapi-docs:# 接口文档路径path: /v3/api-docsgroup-configs:- group: syspaths-to-match: /**packages-to-scan: com.xm.module.sys
# knife4j的增强配置不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn启动程序测试
配置好了之后我们就可以启动程序访问我们刚才配置的路径了这里有三个路径我们分别用浏览器访问看看。 1、/swagger-ui.html这是 swagger-ui 的页面Springdoc本身也是集成了Swagger3 2、/v3/api-docs这就是 Springdoc 的接口接口文档可以导入到 postman 等工具中。 3、/doc.html这是 Knife4j 的默认界面可以理解为是 swagger-ui 的增强版展示的内容一样只是展示的 ui 变了。 完善文档信息
ok我们上面只是将 Knife4j 引入到我们的项目中了但是里面的接口信息还都是默认的可以通过 swagger-ui 界面看到有一个 user-controller下面有多个接口都是默认的名称这样我们将文档给别人或前端理解起来会很困难所以我们在开发中是要补全这些信息的完善一份持续维护的接口文档。
所以最后一步就是使用 OpenAPI3 的规范注解注释各个 Spring 的 REST 接口。我们先来看看 swagger2 和 openAPI3 的注解差别。 Spwagger2和OpenApi3注解的对应关系 Swagger 2OpenAPI 3注解位置ApiTag(name “接口类描述”)Controller 类上ApiOperationOperation(summary “接口方法描述”)Controller 方法上ApiImplicitParamsParametersController 方法上ApiImplicitParamParameter(description “参数描述”)Controller 方法上 Parameters 里ApiParamParameter(description “参数描述”)Controller 方法的参数上ApiIgnoreParameter(hidden true) 或 Operation(hidden true) 或 Hidden-ApiModelSchemaDTO类上ApiModelPropertySchemaDTO属性上
编写配置类
首先添加一个配置类配置一些项目相关的信息。
Configuration
public class SpringDocConfig {Beanpublic OpenAPI openApi() {return new OpenAPI().info(new Info().title(XM-ADMIN系统接口文档).version(1.0).description(一个数据中台项目的接口文档).termsOfService(http://localhost:9527/).contact(new Contact().name(xiaoming).url(https://github.com/shixiaomingya)).license(new License().name(Apache 2.0).url(http://localhost:9527/)));}}修改 UserController
Tag(name 用户管理)
RestController
RequestMapping(/sys/user)
public class UserController {Resourceprivate UserService userService;GetMapping(/{id})Operation(summary 根据用户ID查询用户)public UserEntity get(PathVariable Long id) {return userService.get(id);}GetMapping(/list)Operation(summary 查询全部)public ListUserEntity lists() {return userService.lists();}GetMapping(/page)Operation(summary 分页查询)public PageUserEntity page(int page, int size) {return userService.page(PageRequest.of(page - 1, size));}PostMappingOperation(summary 新增用户)public void save(RequestBody UserEntity user) {userService.save(user);}PutMappingOperation(summary 修改用户)public void update(RequestBody UserEntity user) {userService.update(user);}DeleteMapping(/{id})Operation(summary 根据用户ID删除用户)public void delete(PathVariable Long id) {userService.delete(id);}
}修改 UserEntity
Data
Entity
Table(name sys_user)
Schema(description 用户实体)
public class UserEntity extends BaseEntity implements Serializable {/*** Id 表示为表 ID* GenerationType.IDENTITY 使用自增长主键*/IdGeneratedValue(strategy GenerationType.IDENTITY)Schema(description 用户ID)private Long id;/*** REQUIRED 表示用户必填*/Schema(description 用户名称, requiredMode Schema.RequiredMode.REQUIRED)private String name;Schema(description 用户昵称)private String nickname;Schema(description 用户年龄)private Integer age;Schema(description 用户邮箱)private String email;/*** hidden 表示不在文档中显示该字段*/Schema(description 用户密码, requiredMode Schema.RequiredMode.REQUIRED, hidden true)private String password;
}修改 BaseEntity
Data
MappedSuperclass
EntityListeners(AuditingEntityListener.class)
Schema(description 基础实体)
public class BaseEntity {CreatedByColumn(name create_user, updatable false)Schema(description 创建用户)private String createUser;LastModifiedByColumn(name update_user)Schema(description 修改用户)private String updateUser;CreatedDateColumn(name create_time, updatable false)Schema(description 创建时间)private Date createTime;LastModifiedDateColumn(name update_time)Schema(description 修改时间)private Date updateTime;
}文档效果图
swagger 界面 knife4j 界面
