文章目录
**技术派项目源码地址 : **
- **Gitee : **技术派 - https://gitee.com/itwanger/paicoding
- **Github : 技术派 - https://github.com/itwanger/paicoding **
Knife4j :
- 官方文档:https://doc.xiaominfo.com/
- 码云地址:https://gitee.com/xiaoym/knife4j
- 示例地址:https://gitee.com/xiaoym/swagger-bootstrap-ui-demo
整合Knife4j
引入依赖
<knife4j.version>4.0.0</knife4j.version>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
编写配置文件 法①
@Configuration
@EnableOpenApi
public class SwaggerConfig {
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo()).enable(true)
.select()
//apis: 添加swagger接口提取范围
.apis(RequestHandlerSelectors.basePackage("www.paicoding.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("技术派")
.description("一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统,采用主流的互联网技术架构、全新的UI设计、支持一键源码部署,拥有完整的文章&教程发布/搜索/评论/统计流程等,代码完全开源,没有任何二次封装,是一个非常适合二次开发/实战的现代化社区项目👍 。")
.contact(new Contact("沉默王二", "https://paicoding.com","www.qing_gee@163.com"))
.version("v1.0")
.build();
}
}
编写配置文件 法②
knife4j:
enable: true
openapi:
title: 技术派
description: 一个基于 Spring Boot、MyBatis-Plus、MySQL、Redis、ElasticSearch、MongoDB、Docker、RabbitMQ 等技术栈实现的社区系统,采用主流的互联网技术架构、全新的UI设计、支持一键源码部署,拥有完整的文章&教程发布/搜索/评论/统计流程等,代码完全开源,没有任何二次封装,是一个非常适合二次开发/实战的现代化社区项目👍 。
version: 1.0.0
concat:
- 一灰灰 | 楼仔 | 沉默王二
- https://paicoding.com
- https://github.com/itwanger/paicoding
license: Apache License 2.0
license-url: https://github.com/itwanger/paicoding/blob/main/License
email: bangzewu@126.com
group:
admin:
group-name: 后台接口分组
api-rule: package
api-rule-resources:
- com.github.paicoding.forum.web.admin
front:
group-name: 前台接口分组
api-rule: package
api-rule-resources:
- com.github.paicoding.forum.web.front
配置名词解释
①、knife4j.enable: 设置为 true 以启用 Knife4j,将在应用程序中启用 Knife4j UI。
②、knife4j.openapi: 这个属性包含了 Swagger API 文档的基本元数据信息,如标题、描述、版本等。
- title: API 文档的标题。
- description: API 文档的详细描述。
- version: API 文档的版本号。
- concat: API 文档的作者信息。包括作者名、网站和 GitHub 仓库。
- license: API 文档的许可证类型。
- license-url: API 文档许可证的链接。
- email: API 文档作者的联系邮箱。
③、knife4j.group: 定义 API 分组。这里有两个分组:admin 和 front。
admin: 后台接口分组。
- group-name: 分组名称。
- api-rule: 分组规则,这里使用的是包规则。
- api-rule-resources: 指定包名,Knife4j 将扫描此包下的所有 API 接口并将它们添加到此分组。
front: 前台接口分组,它下面的属性不再赘述,和 admin 一样。
注解三兄弟 : @ApiOperation、@ApiParam、@ApiModel
- @ApiOperation:用于描述一个具体的 API 操作。通常用于标注在 Controller 类的方法上。
- value:API 操作的简短描述,会显示在 API 文档中。
- notes:API 操作的详细描述,会显示在 API 文档中。
- tags:API 操作的标签,用于对 API 进行分类和分组。
@ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户详细信息")
- @ApiParam:用于描述 API 操作的参数。通常用于标注在 Controller 类的方法参数上。
- name:参数名称。
- value:参数描述。
- required:指示参数是否是必需的,默认为 false。
- defaultValue:参数的默认值。
- allowableValues:允许的参数值范围。
public ResponseEntity<User> getUser(@ApiParam(value = "用户 ID", required = true)
@PathVariable("id") Long id) {
// ...
}
- @ApiModel:描述一个 API 操作返回的数据模型, 通常用于标注在实体类或 DTO 类上。
- value:模型名称。
- description:模型描述。
@ApiModel(value = "用户", description = "用户详细信息")
public class User {
// ...
}
启动项目, 访问Knife4j测试
**访问Knife4j地址 : **http://localhost:8080/doc.html
Knife4j优点
支持全局参数
支持离线文档