メインコンテンツまでスキップ
バージョン: Latest(v3.0) 🔥

API Docs Validator

APIドキュメントの検証​

概要​

Path: 左サイドバー → API Document Validation

Menu Type: グループメニュー（サブメニューを含む）

APIドキュメントの検証機能は、API仕様のフォーマットと構造を検証し、検証ステータスを監視する機能を提供します。

アクセス方法​

  1. 左サイドバーの API Document Validation メニューをクリックしてサブメニューを展開します。
  2. 展開されたサブメニューリストから目的の機能を選択します。

💡 注意: APIドキュメントの検証はグループメニューであるため、クリックするとサブメニューの展開と折りたたみが切り替わります。

ユーザーがAPIドキュメントの検証メニューをクリックすると、以下のサブメニューが表示されます:

  1. API Document Settings – API検証ルールの設定
  2. API Document Status Dashboard – 検証ステータスの表示と監視

APIドキュメント設定​

機能概要​

APIドキュメント設定ページでは、ユーザーがAPI Docs Validatorのための検証ルールセットを定義、管理、適用することができます。ユーザーがカスタマイズ可能なルールセットを作成し、検証機能を設定し、特定のプロジェクトにマッピングすることを可能にすることで、標準化されたAPIドキュメントの品質をサポートします。

ページ構造​

Main Section
  1. API Docs Validator Setting
    • ルールセット管理
    • プロジェクトマッピング
  2. Validation Ruleset Management
    • 既存のルールセットリストの表示と管理
  • Add New Ruleset ボタン
  1. Project Selection
    • プロジェクトドロップダウンを使用して特定のプロジェクトを選択します

主な機能​

  • Validation Ruleset Management: 検証ルールセットの作成、編集、および削除
  • Add New Ruleset: 事前定義されたテンプレートを使用して新しいルールセットを作成し、検証関数を追加または削除してカスタマイズ
  • Project Mapping: 特定のプロジェクトに検証ルールセットを関連付ける
  • Default Rulesets
    • OWASP Top10: OWASPトップ10のセキュリティ脆弱性に基づく検証ルール
    • OAS(2.X, 3.X): OpenAPI仕様のための検証ルール

使用方法​

  1. 左側のサイドバーでAPI Document Validationメニューをクリックしてサブメニューを展開します
  2. サブメニューでAPI Document Settings を選択します
  3. Project ドロップダウンからプロジェクトを選択します（オプション）
  4. Validation Ruleset Management セクションで既存のルールセットを確認または管理します
  5. 新しい検証ルールセットを作成するにはAdd New Rulesetをクリックします
    • Add New Rulesetをクリックすると、3つのテンプレートが表示されるモーダルダイアログが表示されます:
      • Default Rule
      • Basic Rule
      • Advanced Rule
    • ルールセット情報を入力します: ルールセット名、説明を入力します
    • テンプレートを選択し、その検証関数をカスタマイズします:
      • Functions Listを開いて、テンプレートに含まれるすべての検証関数を表示します
      • エディタから既存の関数を削除して新しい関数を追加するには、関数をクリックします
      • 関数名にマウスを合わせると、短い説明が表示されます
      • 関数リストの下のリンクをクリックして新しいタブで開きます
  6. ルールセット管理リストに新しいアイテムを追加するには、Saveボタンをクリックします。

ルールセットの種類​

  • OWASP Top10: 上位10のWebアプリケーションセキュリティ脆弱性を検証します
  • OAS(2.X, 3.X): Validates OpenAPI Specification versions 2.x and 3.x

注意事項​

  • ⚠️ ルールセットの変更は、効果を得るために保存する必要があります
  • ⚠️ バリデーションルールが特定のプロジェクトにのみ適用される場合は、プロジェクトマッピングを使用する必要があります

APIドキュメントステータスダッシュボード​

機能説明​

APIドキュメントステータスダッシュボードは、ユーザーがAPIフォーマットのバリデーション実行履歴と結果を表示および監視できるようにします。

ページ構造​

Validation History Table

バリデーション実行履歴をテーブル形式で表示します。

列名説明
リクエスターバリデーションをリクエストしたユーザー
プロジェクト名対象プロジェクト
API名対象API
ステータスバリデーションステータス（合格 / 不合格など）
エラー数検出されたエラーの数
エラー原因バリデーション失敗の理由
バリデーション時間実行の日付と時間
アクション詳細を表示、バリデーションを再実行など

主な機能​

  • View Validation History: 過去のバリデーション実行をレビュー
  • Monitor Validation Status: 合格/不合格の結果を確認
  • Error Analysis: エラー数と原因をレビュー
  • Filtering: プロジェクトドロップダウンを使用してプロジェクトでフィルタリング（オプション）

使用方法​

  1. 左のサイドバーで API Document Validation メニューをクリックしてサブメニューを展開します
  2. サブメニューで API Document Settings を選択します
  3. Validation History テーブルでバリデーション実行履歴を確認します。
  4. Project ドロップダウンを使用して特定のプロジェクトを選択してフィルタリングします（オプション）。
  5. テーブルの Actions 列を使用して、詳細を表示したり、追加のアクションを実行したりします。

テーブル機能​

  • Pagination: 履歴が大きい場合、結果をページごとに表示します。
  • Sorting: 列のヘッダーをクリックしてソートします（サポートされている場合）。
  • Detail View: アクション列を介して詳細情報を表示します。

使用のヒント​

  • 💡 Project Filtering: プロジェクトのドロップダウンを使用して、特定のプロジェクトの検証履歴を表示します。
  • 💡 Status Check: ステータス列を介して合格/不合格の結果を迅速に特定します。
  • 💡 Error Analysis: Error Count および Error Cause列を使用して、検証の問題を特定します。
  • 💡 Latest Data: ページを更新して、最新の検証結果を表示します。

Swaggerドキュメント形式の検証​

機能概要​

Swaggerドキュメント形式の検証は、ユーザーがSwagger/OpenAPI定義を入力し、設定されたルールに対して検証することを可能にします。これにより、デプロイ前にSwaggerドキュメントの標準準拠の問題やエラーを特定するのに役立ちます。

ページ構造​

1. Project Configuration Section
  • Project Selection: 検証するプロジェクトを選択します。
    • 例: otel-prj
  • 選択したプロジェクトに基づいて、適用される検証ルールが自動的に読み込まれます。
2. Applied Validation Rules Section

選択したプロジェクトに適用されたルールセットとルールを表示します:

  • Ruleset Name: 適用されたルールセットの名前（例: MCP Swagger）
  • Applied Rules Examples:
    • mcp-operation-id-required: operationIdの検証が必要
    • mcp-operation-id-style: operationIdスタイルの検証
  • mcp-operation-summary-required: operation summary validation required
    • mcp-json-request-body: JSON request body validation
    • mcp-json-request-body-schema: JSON request body schema validation
    • その他のルール
  • Rule count: 合計ルール数を表示します（例: "および N の追加ルールが適用されました"）
3. Swagger JSON Input Section
  • Input Field: ユーザーがSwagger/OpenAPI JSON定義を入力できる大きなテキストエリアです。
    • デフォルトのガイドメッセージ: "Swagger JSONを入力してください"
    • OpenAPI 3.0形式のSwagger定義をサポート
  • Load Sample Button: 入力フィールドの右上隅にある青いボタン。
    • サンプルSwagger定義（例: Petstoreの例）を入力フィールドに自動的に読み込みます
    • ユーザーが入力形式を確認し、テスト検証を行うことを可能にします
  • Validation Status Indicators: 入力フィールドの下にJSON検証結果を表示します。
    • 有効なJSON: JSON形式が有効な場合、緑のチェックアイコンで表示されます
    • OpenAPI仕様: 定義がOpenAPI仕様に準拠している場合、緑のチェックアイコンで表示されます
  • Run Swagger Validation Button: ページの中央下部にある大きな青いボタン。
    • 入力されたSwagger JSONに対してすべての設定された検証ルールを実行します
    • クリックするとすぐに検証が開始され、結果が下に表示されます
  • Export Results Button: 検証実行ボタンの隣にある緑のボタン
    • ユーザーが検証結果をファイルにエクスポートできるようにします
4. Validation Results Section

検証が実行された後、結果はページの下部に表示されます。

Summary Information (トップカード形式):

  • ERROR: 検出されたエラーの数、赤い背景で表示されます
    • 例: 1エラー
  • WARNING: 検出された警告の数、オレンジの背景で表示されます
    • 例: 0警告
  • SUCCESS: 成功したバリデーションの数、緑の背景に表示されます
    • 例: 8 成功
  • FAIL - Total N Issues: バリデーションの問題の総数、赤いラベルで表示されます
    • 例: FAIL - 合計 1 問題
Detailed Results Table:
カラム名説明
SeverityERROR（赤）またはSUCCESS（緑）を表示
Rule適用されたバリデーションルール名（例: mcp-json-request-body）
Messageバリデーション結果メッセージ（例: "content" プロパティは...を持っている必要があります）
Pathエラーが発生したSwagger定義内のパス
Ruleset nameルールが属するルールセットの名前
Action“View Detail”ボタンをクリックして各項目の詳細情報を表示
Table function:
  • Pagination: 大量のバリデーション結果が存在する場合、ページごとに結果を表示します（例: “ページあたりの行数: 10”）
  • Sorting: カラムヘッダーをクリックして結果をソートします
  • Detail View: Action カラムのView Detailsボタンをクリックして各バリデーション項目の詳細情報を表示します

主な機能​

1. Apply Project-specific validation rules
  • プロジェクトが選択されると、そのプロジェクトにマッピングされたバリデーションルールが自動的に適用されます。
  • 各プロジェクトに異なるバリデーションルールを適用できます。
2. Swagger JSON input and validation
  • 開発されたAPIのSwagger/OpenAPI定義を直接入力してバリデーションできます。
  • JSON形式の有効性とOpenAPI仕様の準拠をリアルタイムで確認します。
3. Sample load function
  • Sample Loadボタンをクリックすると、サンプルSwagger定義が自動的に入力されます。
  • サンプルは、必要な入力形式を確認し、機能をテストするために使用できます。
4. Run validation and view results
  • Run Swagger Validationボタンをクリックして、すべての設定されたバリデーションルールを実行します。
  • バリデーション結果は、エラー、警告、または合格として分類されます。
  • 各検証項目（ルール、メッセージ、パス）に関する詳細情報を表示できます。
5. Export results
  • 検証結果は、ドキュメント作成や共有のためにファイルとしてエクスポートできます。

使用方法​

Basic Validation Process
  1. Select Project: 上部の project to be validated ドロップダウンから、検証するプロジェクトを選択します。
  2. Check Validation Rules: Applied Validation Rules セクションのルールのリストを確認します。
  3. Enter Swagger JSON:
    • Method 1:  開発したAPIのSwagger JSONをコピーし、入力フィールドに貼り付けます。
    • Method 2:  Load Sample ボタンをクリックして、サンプルSwaggerを読み込み、修正します。
  4. Check JSON Validity: 入力フィールドの下部で、Valid JSON およびOpenAPI Specのインジケーターを確認します。
  5. Run Validation: Run Swagger Validation ボタンをクリックします。
  6. Review Results: 下部の Validation Results セクションで、要約情報と詳細結果の両方を確認します。
  7. Fix Errors: エラーが見つかった場合は、メッセージとパス情報を参照してSwagger定義を修正します。
  8. Re-validate: 修正後、再度検証を実行してすべてのエラーが解決されたことを確認します。

実用的な使用シナリオ​

Scenario 1: Swagger Validation After Development Completion
  1. API開発が完了したら、Swagger/OpenAPI 定義を生成します。
  2. 左のサイドバーから API Management > API Format Validation に移動します。
  3. project to be validated セクションで検証するプロジェクトを選択します。
  4. 生成されたSwagger JSONをコピーし、入力フィールドに貼り付けます。
  5. Run Swagger Validation ボタンをクリックします。
  6. 結果を確認し、エラーを修正します。
  7. すべての検証が通過するまで繰り返します。

Scenario 2: Validation Test Using Sample  

  1. project to be validatedを選択します。
  2. サンプルSwaggerを読み込むには、Load Sampleボタンをクリックします。
  3. サンプルSwaggerを参照して、実際のSwagger定義を作成します。
  4. Run Swagger Validationボタンをクリックして、検証します。
  5. 結果を確認し、必要な修正を行います。
Scenario 3: Validation Rule Compliance Check
  1. 適用された検証ルールを確認するためにプロジェクトを選択します。
  2. Swagger JSONを入力します。
  3. 検証を実行します。
  4.  Detailed results tableで、各ルールの検証結果を確認します。
  5. ERRORおよびWARNINGのあるルールを確認し、修正します。
  6. エラーに関する詳細情報を表示するには、View Detailsボタンをクリックします。

使用例​

Example 1: Basic Validation Execution
  1. otel-prjプロジェクトを選択します。
  2. サンプルSwaggerを読み込むには、Load Sampleをクリックします。
  3. Run Swagger Validationをクリックします。
  4. 検証結果を確認します：
    • エラー: 1
    • 警告: 0
    • 合格: 8
Example 2: Actual Swagger Validation
  1. 完成したAPIのSwagger JSONをコピーします。
  2. プロジェクトを選択します（例：otel-prj）。
  3. 入力フィールドにSwagger JSONを貼り付けます。
  4. JSONの有効性を確認します（有効なJSON、OpenAPI Specを確認）。
  5. Run Swagger Validationボタンをクリックします。
  6. 検証結果のエラーを確認します：
    • 例：mcp-json-request-bodyルールの違反
    • メッセージ："content"プロパティには必須プロパティ"application/json"が必要です。
    • パス：paths./pet/{petId}/uploadImage.post.requestBody.content
  7. Swagger定義内のこのパスのエラーを修正します。
  8. 修正後に検証を再実行します。
  9. すべての検証が合格することを確認します。
Example 3: Validation Result Analysis
  1. 検証を実行した後、Validation Resultsセクションを確認します。
  2. summary informationで問題の総数を確認します（例：FAIL - 合計1件の問題）。
  3. Detailed results tableで各項目を確認します：
    • Severity：ERRORのある項目を優先して確認します。
    • Rule：どのルールが失敗したかを確認します。
  • Message: 特定のエラー詳細を確認する
    • Path: Swagger定義内の正確な位置を確認する必要があります
  1. 追加情報についてはView Detailsをクリックしてください
  2. エラーを修正し、再度検証を実行します

Cautions​

  • ⚠️ Project Selection Required: 各プロジェクトで検証ルールが異なる場合があるため、正しいプロジェクトを選択する必要があります。
  • ⚠️ JSON Format Compliance: 入力されたSwaggerは有効なJSON形式でなければならず、OpenAPI仕様に準拠している必要があります。
  • ⚠️ Validation Rule Review: プロジェクトに適用される検証ルールを事前に確認し、すべての必須項目が適切に遵守されるようSwaggerを準備してください。
  • ⚠️ Re-validation After Fixing: エラーを修正した後、すべての問題が解決されたことを確認するために再度検証を実行してください。
  • ⚠️ Save Validation Results: 重要な検証結果を保存するためにresultエクスポート機能を使用してください。

Usage Tips​

  • 💡 Use Samples: 初めて使用する場合は、必要な入力形式を確認するためにload sampleボタンを使用してください。
  • 💡 Real-time Validation: JSONを入力している間、リアルタイム検証のためにValid JSONおよびOpenAPI Specインジケーターを確認してください。
  • 💡 Rule-based Filtering: 検証結果テーブルはルールでフィルタリングでき、特定の検証ルールの結果のみを表示できます。
  • 💡 Path Utilization: 検証結果のパス情報は、Swagger定義内の正確な位置を特定し、修正するために使用できます。
  • 💡 Repeated validation: 開発中に定期的に検証を実行することは、エラーを早期に検出し解決するのに効果的です。