Knife 4 Jの戦い

Knife 4 Jコア知識

Knife 4 Jとは？

Knife 4 jは、Java Webプロジェクトのためのインターフェイスドキュメント拡張ソリューションです。アプリケーションによって生成されたOpen APIドキュメントを読み取ることができ、より使いやすいインターフェイスプレゼンテーション、オンラインデバッグ、検索、ソート、オフラインエクスポート、アクセス制御などの機能を提供します。

Spring Boot 3プロジェクトでは、関連するコンポーネントは次のような関係として理解できます。

Open API 3：RESTful APIの仕様を記述します。
springdoc-openapi：Spring WebインターフェイスをスキャンしてOpen API 3ドキュメントを生成します。
Swagger UI：Open APIドキュメントを表示およびデバッグするための共通のWebインターフェイス。
Knife 4 j：Open APIドキュメントに基づく拡張されたインターフェイスと拡張機能を提供します。

したがって、Knife 4 jは新しいインタフェース仕様ではなく、Open API 3と同等でもない。Spring Boot 3プロジェクトでは、Knife 4 jの基盤となるドキュメント生成機能は主にspringdoc-openapiによって提供される。

Spring Boot 2とSpring Boot 3の主な違い

比較	Spring Boot 2 共通シナリオ	Spring Boot 3 推奨シナリオ
Javaバージョン	は通常 JDK 8 以上を使用できます。Spring Bootバージョン	に応じてJDK 17
Java EEパッケージ名	主に`javax.*`	を使用して`jakarta.*`
インターフェイス·ドキュメント仕様	はOpen API 2またはOpen API 3	推奨 Open API 3
一般的な実装	Spring foxまたはSpring doc-openapi	Spring doc-openapi
Knife 4 j Starter	仕様とフレームワークのバージョンに基づいて対応するStarter	を選択 Jakartaバージョンを使用したOpen API 3 Starter
共通注釈	古いプロジェクトは`io.swagger.annotations.*`	使用`io.swagger.v3.oas.annotations.*`

注：Spring Boot 3 自体が“Swagger 2アノテーションを廃止”したわけではなく、Spring Boot 3プロジェクトは通常、古いSpringfoxベースのスキームを使用しなくなった。springdoc-openapiに移行したら、古い注釈をOpenAPI 3 注釈に置き換える必要があります。

Knife 4 jのSwagger UIの一般的な拡張機能

の比較	Swagger UI	Knife 4 j
ページの表示	標準のOpenAPIドキュメントインターフェイスを提供	中国語プロジェクトに適したインターフェイスの強化
インタフェースのデバッグ	オンラインでリクエストを送信できます	パラメータの入力、リクエストのデバッグ、結果の表示を強化
インタフェースの取得	基本フィルタリングのサポート	インターフェイス検索などの拡張機能を提供
ドキュメントの書き出し	完全なオフラインエクスポートプロセスはデフォルトでは提供されません	Markdown、HTML、Word、Open APIドキュメントのエクスポートをサポート
拡张	Swagger UIの設定項目の使用	Knife4jの拡張設定を追加
アクセスの保護	通常、セキュリティフレームワークと組み合わせる必要があります。	本番環境保護やBasic 認証などの補助構成を提供

適用可能なシーン

フロントとリアの分離プロジェクトでインターフェースドキュメントを自動生成して維持します。
開発およびテスト段階では、インターフェイスをオンラインで呼び出します。
リクエストパラメータ、レスポンス構造、ステータスコード、フィールドの説明を表示します。
マルチモジュールまたはマイクロサービスプロジェクトにおける統合管理インターフェイスのドキュメント。
インターフェイスドキュメントをエクスポートして、納品またはアーカイブに使用します。

Spring Boot 3とKnife 4 j

環境要件は

この記事では、次の環境を使用します。

JDK 17 以降。
Spring Boot 3.x。
Mavenプロジェクト。
spring-boot-starter-web.
Knife4J 4.5.0。

実際のプロジェクトでは、Spring Bootの特定のバージョンに対して依存性互換性をチェックする必要があります。“より高いバージョン”だけでコンポーネント互換性を判断するのではなく。

Maven 依存性の導入

Spring Boot 3はKnife 4 j Starterのジャカルタ版を使用しています。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

StarterはOpen API 3に必要なspringdoc-openapi 関連の依存関係を統合しています通常、Springfox、Swagger 2、または他のバージョンのspringdoc-openapiを個別に導入する必要はありません。

application.ymlの設定

単一モジュールプロジェクトに適した基本構成を以下に示します。

server:
  port: 8080

spring:
  application:
    name: knife4j-spring-boot3-demo

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: default
      paths-to-match: /**
      packages-to-scan: com.example.knife4jdemo.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

設定の手順：

springdoc.api-docs.pathはOpen API JSONドキュメントアドレスの設定に使用されます。
springdoc.group-configsは、ドキュメントグループ化、インタフェースパス、およびコントローラスキャンパッケージの設定に使用されます。
packages-to-scanは、現在のプロジェクトの実際のコントローラパッケージ名に置き換える必要があります。
knife4j.enableはKnife 4 jの拡張機能を有効にするために使用されます。
knife4j.setting.languageはインタフェース言語を設定するために使用される。

構成インタフェース·ドキュメントの基本情報

OpenAPI Beanを宣言することで、ドキュメントのタイトル、バージョン、説明、連絡先情報を統一的に設定できます。

package com.example.knife4jdemo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jOpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户管理系统接口文档")
                        .version("1.0.0")
                        .description("基于 Spring Boot 3、OpenAPI 3 和 Knife4j 构建的接口文档")
                        .contact(new Contact()
                                .name("项目开发组")
                                .email("demo@example.com"))
                        .license(new License()
                                .name("Apache 2.0")));
    }
}

プロジェクトを起動し、ドキュメントにアクセスする

Spring Bootプロジェクトを起動した後、ブラウザで次の手順にアクセスします。

http://localhost:8080/doc.html

Open API JSONドキュメントのデフォルトのアクセスアドレスは/v3/api-docsです。グループ化が設定されている場合は、対応するグループ化された文書アドレスも生成されます。

`doc.html`にアクセスできない場合のトラブルシューティング手順

通常、Starterの導入後に静的リソースマッピングを手動で設定する必要はありません。404、401、または403が表示された場合は、次の順序でトラブルシューティングしてください。

Maven 依存関係がSpring Boot 3 対応のJakarta Starterを使用しているか確認します。
複数のspringdoc-openapiまたはSpringfoxバージョンが誤って導入されていないか確認します。
packages-to-scanが実際のコントローラパッケージパスであるかどうかを確認します。
プロジェクトが@EnableWebMvcを使用しているかどうか、Spring MVC 構成を完全に引き継いでいるかどうかを確認します。
Spring SecurityがドキュメントページとOpen APIドキュメントインターフェイスをブロックしていないか確認します。
アプリケーションがcontext-pathで構成されているかどうか、アクセスアドレスにコンテキストパスを追加する必要があるかどうかを確認します。

補足リソースマッピングは、プロジェクトが静的リソース規則をカスタマイズし、自動構成が有効でないことを確認した場合にのみ考慮されます。

package com.example.knife4jdemo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebResourceConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

この構成はトラブルシューティングシナリオであり、すべてのSpring Boot 3プロジェクトに必須ではありません。

Open API 3 共通のコメント

旧注釈と新注釈の対照

の機能	レガシー Swagger 2 注釈	OpenAPI 3 注釈
コントローラーのグループ化	`@Api`	`@Tag`
インタフェースの説明	`@ApiOperation`	`@Operation`
パラメータの説明#パラメータノサクセイ#	`@ApiParam`、`@ApiImplicitParam`	“
複数のパラメータの説明	ApiImplicitParams`	`@パラメータ`
モデルの説明	`@ApiModel`	`@Schema`
フィールドの説明	`@ApiModelProperty`	`@Schema`
インタフェースまたはクラスの非表示	`@ApiIgnore`	`@Hidden`または`@Operation hidden = true`

`@Schema`によるエンティティークラスの記述

package com.example.knife4jdemo.domain;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息")
public class User {

    @Schema(
            description = "用户主键",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "10001"
    )
    private Long id;

    @Schema(
            description = "用户名",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "zhangsan"
    )
    private String username;

    @Schema(
            description = "手机号码",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "13800138000"
    )
    private String phone;

    @Schema(description = "年龄", example = "26")
    private Integer age;

    @Schema(description = "用户状态：0 表示禁用，1 表示正常", example = "1")
    private Integer status;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }
}

Lombokを使用するプロジェクトでは、@Dataを使用してGetterとSetterを簡素化できますが、プロジェクトにLombokが正しく導入され、注記処理が有効になっていることを確認する必要があります。

`@Tag`および`@Operation`を使用したコントローラの記述

package com.example.knife4jdemo.controller;

import com.example.knife4jdemo.domain.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "提供用户查询接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(
            summary = "根据编号查询用户",
            description = "根据用户主键查询用户详细信息"
    )
    public User getUserById(
            @Parameter(
                    description = "用户主键",
                    required = true,
                    example = "10001"
            )
            @PathVariable("id") Long id
    ) {
        User user = new User();
        user.setId(id);
        user.setUsername("zhangsan");
        user.setPhone("13800138000");
        user.setAge(26);
        user.setStatus(1);
        return user;
    }

    @GetMapping
    @Operation(
            summary = "查询用户列表",
            description = "查询当前系统中的用户数据"
    )
    public List<User> listUsers() {
        return List.of(getUserById(10001L));
    }
}

プロジェクト再開後の訪問：

http://localhost:8080/doc.html

ページには、ユーザー管理グループ、インターフェイスの概要、パラメータの説明、および応答モデルを表示する必要があります。

Knife 4 jの機能

グローバルJWT 認証の構成

JWTを使用するプロジェクトでは、Open APIドキュメントでHTTP Bearer 認証スキームを宣言できます。次の構成は、以前のOpenAPI Beanのアップグレード版であり、実際のプロジェクトには1つのOpenAPI Beanのみが残ります。

package com.example.knife4jdemo.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jOpenApiConfig {

    private static final String SECURITY_SCHEME_NAME = "BearerAuth";

    @Bean
    public OpenAPI customOpenAPI() {
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .description("输入登录后获得的 JWT");

        return new OpenAPI()
                .info(new Info()
                        .title("用户管理系统接口文档")
                        .version("1.0.0")
                        .description("支持 JWT 调试的接口文档")
                        .contact(new Contact()
                                .name("项目开发组")
                                .email("demo@example.com"))
                        .license(new License()
                                .name("Apache 2.0")))
                .components(new Components()
                        .addSecuritySchemes(SECURITY_SCHEME_NAME, securityScheme))
                .addSecurityItem(new SecurityRequirement()
                        .addList(SECURITY_SCHEME_NAME));
    }
}

設定が完了すると、ドキュメントページに認証ポータルが表示されます。開発者がJWTを入力すると、デバッグリクエストはBearer 認証に従ってAuthorizationリクエストヘッダーを運びます。

注：OpenAPIオブジェクトにセキュリティスキームを追加すると、ドキュメントはデフォルトで認証を必要としますが、Spring Securityのサーバー側認証ロジックを置き換えるものではありません。

オフラインドキュメントのエクスポート

Knife 4 jのドキュメント管理機能は、以下のものをエクスポートできます。

Markdownドキュメント。
オフラインのHTMLドキュメント。
Wordドキュメント。
オリジナルのOpen API JSONドキュメント

Knife 4 jエクスポート機能はPDFを直接生成しません。PDFが必要な場合は、MarkdownまたはHTMLをエクスポートし、他のツールを使用してPDFに変換できます。

表示する必要のないインターフェイスを隠す

@Hiddenを使用すると、コントローラまたはインタフェースを非表示にできます。

package com.example.knife4jdemo.controller;

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Hidden
@RestController
@RequestMapping("/admin")
public class AdminController {

    @PostMapping("/password")
    public String updatePassword() {
        return "密码修改成功";
    }
}

1つのメソッドだけを非表示にすることもできます。

@Hidden
@PostMapping("/internal/reset")
public String resetData() {
    return "重置成功";
}

重要事項：@Hiddenは、インターフェイスがOpen APIドキュメントに表示されるかどうかを制御するだけで、クライアントがインターフェイスにアクセスするのをブロックしません。機密インターフェイスは、Spring Security、パーミッションチェックサムゲートウェイポリシーで保護する必要があります。

本番環境のセキュリティ構成

開発環境の設定

開発環境はインターフェイスドキュメントを開くことができます。

knife4j:
  enable: true
  production: false

本番環境のシャットダウンに関する文書

本番環境では、Knife 4 jページ、Swagger UI、Open API JSONインターフェイスを同時に閉じることができます。

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

knife4j:
  enable: false
  production: true

そのうち：

knife4j.productionはKnife 4 jの本番環境保護ポリシーを有効にするために使用されます。
springdoc.api-docs.enabledはOpen API JSONインターフェイスを閉じるために使用される。
springdoc.swagger-ui.enabledはSwagger UIをオフにするために使用されます。

本番環境でインターフェイスドキュメントを完全に無効にするかどうかは、プロジェクトのネットワーク分離、権限モデル、運用要件に基づいて決定する必要があります。

Basic 認証を使用したドキュメントの保護

内部テスト環境でオープンドキュメントが必要な場合は、Basic 認証を有効にできます。

knife4j:
  enable: true
  production: false
  basic:
    enable: true
    username: doc_user
    password: ${KNIFE4J_PASSWORD}

実際のパスワードをコードストアに直接保存しないでください。例環境変数KNIFE4J_PASSWORDを使用したパスワード注入。

Basic 認証は、ドキュメントアクセス保護の一部としてのみ使用できます。本番システムには、HTTPS、ネットワークアクセス制御、Spring Security、Unified Authenticationなどの対策も組み込む必要があります。

よくある質問

ページは開くが、インターフェイスがない

主なチェック：

packages-to-scanが正しく構成されているかどうか。
コントローラは@RestControllerを使用しています。
要求メソッドは@GetMapping，@PostMappingなどのマッピング注記を用いているかどうか.
コントローラがSpring Bootのデフォルトのスキャン範囲内にあるかどうか。
paths-to-matchが誤って構成されているかどうか。

ドキュメントページが`401`または`403`に戻る

これは通常、リクエストがセキュリティフィルタによって傍受されることを示します。開発環境では、以下のリソースをオンデマンドでリリースする必要があります。

/doc.html
/webjars/**
/v3/api-docs/**
/swagger-ui/**
/swagger-ui.html

リリースするかどうかは、プロジェクトが実際に使用するSpring Securityのバージョンとパーミッションポリシーに基づいて行われます。

ドキュメントページは`404`に戻る

主なチェック：

スターターは正しい選択をします。
ダウンロードが成功したかどうかに依存します。
依存関係の対立がある。
適用コンテキストパスが設定されているかどうか。
自動構成が@EnableWebMvcで上書きされているかどうか。
静的リソースマッピングがカスタマイズされているかどうか。

注記がドキュメントに表示されません

コールアウトパッケージがio.swagger.v3.oas.annotationsからのものであるかどうかを確認します。古いio.swagger.annotationsとOpen API 3アノテーションを混ぜないでください。

インタフェースを変更してもドキュメントは変更されない

順番に試すことができます：

コードを再コンパイルしてアプリケーションを再起動します。
ブラウザのページを更新します。
Knife 4 jページキャッシュをクリアする
現在表示されているものが正しくグループ化されているかどうかをチェックします。
/v3/api-docsに直接アクセスして、バックエンドで生成されたOpen API JSONが更新されているか確認します。

概要まとめ

Spring Boot 3のKnife 4 j 統合のコアプロセスは以下のとおりです。

JDK 17 以上を使用しています。
Knife 4 j Open API 3 StarterのJakarta 版を導入。
springdocを使用して、パッケージ、グループ化、Open APIドキュメントパスをスキャンします。
OpenAPI Beanからドキュメントプロフィールと認証スキームを設定します。
インタフェースは、@Tag、@Operation、@Parameter、および@Schemaを使用して記述される。
開発環境ではドキュメントをオープンにし、本番環境ではセキュリティ要件に従ってアクセスを閉じたり制限したりします。
“隠されたインターフェイスドキュメント”と“実際のインターフェイスを保護する”を明確に区別し、@Hiddenを権限制御手段として使用することはできません。

Knife 4 Jの戦い

Knife 4 Jの戦い

Knife 4 Jコア知識

Knife 4 Jとは？

Spring Boot 2とSpring Boot 3の主な違い

Knife 4 jのSwagger UIの一般的な拡張機能

適用可能なシーン

Spring Boot 3とKnife 4 j

環境要件は

Maven 依存性の導入

application.ymlの設定

構成インタフェース·ドキュメントの基本情報

プロジェクトを起動し、ドキュメントにアクセスする

doc.htmlにアクセスできない場合のトラブルシューティング手順

Open API 3 共通のコメント

旧注釈と新注釈の対照

@Schemaによるエンティティークラスの記述

@Tagおよび@Operationを使用したコントローラの記述

Knife 4 jの機能

グローバルJWT 認証の構成

オフラインドキュメントのエクスポート

表示する必要のないインターフェイスを隠す

本番環境のセキュリティ構成

開発環境の設定

本番環境のシャットダウンに関する文書

Basic 認証を使用したドキュメントの保護

よくある質問

ページは開くが、インターフェイスがない

ドキュメントページが401または403に戻る

ドキュメントページは404に戻る

注記がドキュメントに表示されません

インタフェースを変更してもドキュメントは変更されない

概要まとめ

`doc.html`にアクセスできない場合のトラブルシューティング手順

`@Schema`によるエンティティークラスの記述

`@Tag`および`@Operation`を使用したコントローラの記述

ドキュメントページが`401`または`403`に戻る

ドキュメントページは`404`に戻る