Knife4j の紹介
Knife4j は、Swagger に基づいて API ドキュメントを生成するための拡張ツールであり、開発者が RESTful API ドキュメントを構築および管理するプロセスを簡素化します。Knife4j は、プロジェクト内のインターフェース情報を自動的にスキャンすることで、手動での作成やメンテナンスを行わずに、詳細で読みやすい API ドキュメントを生成できます。インターフェイスの正確性の検証を容易にする対話型のインターフェイス デバッグ ページを提供し、大規模なプロジェクトでのインターフェイスの管理を容易にするインターフェイスの集約とグループ化をサポートします。さらに、Knife4j は Markdown ドキュメントとカスタマイズされた構成オプションもサポートしているため、API ドキュメントがより美しく、柔軟で、表示しやすくなります。全体として、Knife4j は API ドキュメントの品質と開発効率を向上させ、チームのコラボレーションとコミュニケーションを促進できる強力なツールです。
依存関係の導入
Knife4j実際、これはかなりアップグレードされたバージョンで、 SwaggerBi よりもはるかにSwagger使いやすくなっています。
<!-- Knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.0.0</version>
</dependency>
Knife4j 構成クラス
package com.hsqyz.config.common;
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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
/**
* Knife4j 配置
*/
@Configuration
@EnableSwagger2WebMvc // 开启Swagger
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(true)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(new ApiInfoBuilder()
.title("API接口文档")
.description("API接口文档描述")
.termsOfServiceUrl("http://127.0.0.1:8080/")
// 联系方式(这里以本人邮箱为例)
.contact("[email protected]")
.version("1.0.0")
.build()
)
// 分组名称
.groupName("default")
// 设置哪些接口暴露给Swagger展示
.select()
// 这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.hsqyz.controller"))
// 路径选择器
.paths(PathSelectors.any())
.build()
/**
* 设置安全模式，swagger可以设置访问token
*/
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping("/");
}
/**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
リリースノート
エラーが発生した場合:
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
凡例の問題
ここでは 2 つの修理オプションが利用可能です
Spring Boot バージョンを 2.6.x より前のバージョンに下げる
たとえば、次のバージョンの組み合わせは互換性があります。
| Spring Boot バージョン | スワッガーバージョン |
|---|---|
| 2.5.6 | 2.9.2 |
SpringBootのバージョンをダウングレードしない場合の解決策
構成ファイルに以下を追加します。
プロパティの形式
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
yaml形式
spring:
mvc:
pathmatch:
matching-strategy=ant_path_matcher
プロジェクトの実行後、ip+ポート番号+/doc.html にアクセスします (例: http://localhost:8080/doc.html)。
グローバルパラメータ
実際のプロジェクトでは、アクセス インターフェイスにアクセス許可が追加され、各アクセスにはリクエスト ヘッダー パラメーター トークンが必要です。グローバル パラメーターは、固定パラメーターを渡すためだけの便宜のためのものです。グローバル パラメータが追加されると、すべてのインターフェイスがこのパラメータを保持します。
グローバルパラメータを設定するには2つの方法があります
1つ目の【エンコード方式】
securitySchemes()と を使用して参照コードsecurityContexts()を設定します
/**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
効果: メニューにリクエスト ヘッダーがもう 1 つありますAuthorize。パラメータ値に情報を追加します
。更新してインターフェイスを再度開きます。リクエスト ヘッダーがさらにあることがわかります。
2 番目のタイプ [グローバル パラメータを手動で設定する]
メニュー文档管理→で直接全局参数设置パラメータを追加します:
追加して保存し、
インターフェイスを開くと、リクエスト ヘッダー パラメータが追加されていることがわかります。
フィルタインターセプト命令
SaToken( 、SpringSecurity、手動で定義したインターセプターやフィルターを含む)などのセキュリティ関連のフレームワークを使用している場合、Knife4jドキュメント インターフェイスがインターセプトされ、ドキュメントの読み込みに失敗する可能性があるため、このインターフェイスを手動で解放する必要があります。
Apifox はワンクリックでナイフ 4j インターフェースドキュメントをインポートします
[インポート プロジェクトの
選択]をクリックしKnife4j、アドレスを入力して解析します。
解析されたアドレスは、グループ インターフェイスの詳細情報のアドレスであり、[送信] をクリックします。
参考記事
Knife4j インターフェースを統合した Spring Boot プロジェクトのコード例 ドキュメント
Knife4j v2.0 ユーザーガイド