前言

前面一小節我們使用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 依賴

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.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: 'sys'paths-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 2	OpenAPI 3	注解位置
@Api	@Tag(name = “接口類描述”)	Controller 類上
@ApiOperation	@Operation(summary = “接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description = “參數描述”)	Controller 方法上 @Parameters 里
@ApiParam	@Parameter(description = “參數描述”)	Controller 方法的參數上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO類上
@ApiModelProperty	@Schema	DTO屬性上

編寫配置類

首先添加一個配置類，配置一些項目相關的信息。

@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 List<UserEntity> lists() {return userService.lists();}@GetMapping("/page")@Operation(summary = "分頁查詢")public Page<UserEntity> page(int page, int size) {return userService.page(PageRequest.of(page - 1, size));}@PostMapping@Operation(summary = "新增用戶")public void save(@RequestBody UserEntity user) {userService.save(user);}@PutMapping@Operation(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 使用自增長主鍵*/@Id@GeneratedValue(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 {@CreatedBy@Column(name = "create_user", updatable = false)@Schema(description = "創建用戶")private String createUser;@LastModifiedBy@Column(name = "update_user")@Schema(description = "修改用戶")private String updateUser;@CreatedDate@Column(name = "create_time", updatable = false)@Schema(description = "創建時間")private Date createTime;@LastModifiedDate@Column(name = "update_time")@Schema(description = "修改時間")private Date updateTime;
}

文檔效果圖

swagger 界面

knife4j 界面