での API 仕様の検証 API インサイト

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：5分

    • API 仕様の検証ルールにアクセスして、API 仕様が完全で一貫性があり、ベストプラクティスに準拠していることを確認できます。

    検証ルールは、インポートまたは分析の早い段階で構造上の問題を特定し、全体的な API 品質を向上させます。これらのルールを管理して、API 仕様全体で標準化を適用し、API が本番環境で公開または使用される前に不足しているフィールドや誤ったフィールドをチェックすることでエラーを減らすことができます。

    API 仕様の保存

    API 仕様 [sn_api_insights_ws_api_specification] テーブルには、個々の API を記述する仕様ドキュメントが格納されます。各レコードには、仕様が属する API を識別し、複数のバージョンを管理するための次の詳細が含まれています。
    表 : 1. API 仕様の詳細
    フィールド 説明
    名前 API の名前。
    バージョン API のバージョン。
    タイプ 使用されている API 仕様標準の形式とバージョン。たとえば、OpenAPI 仕様の場合は openapi3.0.0 です。
    状況 API 仕様が適用可能なルールおよび検証結果に対して検証されたかどうかを示す現在のステータス。有効な値は次のとおりです。
    • 未処理:API 仕様が検証されていないことを示します。
    • 有効:API 仕様が正常に検証され、処理されたか、警告が表示されたことを示します。警告が表示されている場合は、 詳細が [メッセージ ] フィールドに表示されます。
    • 無効:API 仕様が検証されたが、エラーが含まれていることを示します。エラーの詳細が [メッセージ ] フィールドに表示されます。
    仕様 API 仕様ファイルの完全なコンテンツ。
    注:
    OpenAPI の場合、エンドポイント、メソッド、およびスキーマについて説明する完全な OpenAPI ドキュメントが含まれています。
    メッセージ メッセージは、仕様タイプのすべての検証ルールを処理した後に生成されます。これには、説明付きのエラーまたは警告が含まれます。

    検証ルールの構造

    仕様検証ルール [sn_api_insights_ws_spec_validation_rule] テーブルには、API 仕様 [sn_api_insights_ws_api_specification] テーブルで定義された API 仕様の検証ルールが保存されます。
    注:
    検証ルールを編集または削除するには sn_cmdb_editor ロール、ルールを表示するには cmdb_read ロールが必要です。

    各検証ルールには、次の主要なコンポーネントが含まれています。

    表 : 2. 検証ルールのコンポーネント
    コンポーネント 説明
    仕様 ルールが設計された API 仕様。
    バージョン ルールが検証する API 仕様のバージョン。指定した場合、ルールはそれらのバージョンにのみ適用されます。検証を特定のバージョンに制限するには、[ バージョン ] フィールドで指定します。複数の値はカンマで区切ります。例: 1.0,1.1,2.0。
    注:
    [バージョン] フィールドを空のままにすると、指定した API 仕様タイプのすべてのインストール済みバージョンに対してルールが実行されます。
    タイプ 実行する検証のタイプ。有効な値は次のとおりです。
    • パス:API 仕様ドキュメントの指定されたセクションのオブジェクトのアレイ、個々のオブジェクト、またはその両方の中に特定のキーが存在することを確認します。
    • 予期された値:指定されたキーが [値 ] フィールドで指定された予期された値と一致するかどうかを検証します。この検証は、[ キー ] フィールドで指定された単一のキーにのみ適用されます。
    キー 検証する仕様の一部。想定される値が指定されていない場合は、[ キー ] フィールドに複数のキーをカンマで区切って入力できます。
    値 [キー] フィールドで指定されたキーの予期される値。複数の値はカンマで区切ります。
    重大度 検証ルールの結果の重大度レベル (警告またはエラー)。
    注:
    警告に設定すると、ルールが満たされていない場合、API 仕様は有効なままになり、失敗ではないことが示され、メッセージのみが表示されます。
    メッセージ ルールがトリガーされたときの問題の説明。
    アクティブ ルールをアクティブ化するためのオプションアクティブなルールのみが、 API Specification Validation スケジュール済みジョブによってトリガーされます。

    API 仕様の検証プロセス

    API Specification Validationスケジュール済みジョブは、仕様タイプに基づいてアクティブなルールに対して未処理の API 仕様を自動的に検証し、必要な標準に準拠していることを確認します。

    検証プロセスには次のものが含まれます。
    1. 仕様検証ルール [sn_api_insights_ws_spec_validation_rule] テーブルからすべてのアクティブな検証ルールを取得しています。
    2. API 仕様 [sn_api_insights_ws_api_specification] テーブルで未処理としてマークされた API の選択。
    3. OpenAPI などの仕様タイプに基づいて、選択した各 API に関連する検証ルールを適用します。
    4. API 仕様内の特定のフィールドまたはその値の存在または正確性を検証します。
    5. 処理ステータスを更新し、エラーまたは警告をキャプチャします。

    OpenAPI 仕様の事前定義ルール

    デフォルトでは、アプリケーションには OpenAPI 仕様に関する次の検証ルールが含まれています。
    タグの検証
    API 仕様の各タグに 名前 フィールドが含まれていることを確認します。名前フィールドがない場合、システムは警告メッセージを返しますが、仕様は有効としてマークされます。
    必須セクションを検証
    API 仕様に、必須の最上位セクション ( 情報、 パス、 およびコンポーネント) が含まれていることを確認します。これらのセクションのいずれかが欠落している場合、システムはエラーメッセージを返し、仕様を無効としてマークします。
    [サーバーの検証] セクション
    API 仕様にサーバーエンドポイントを定義する サーバー セクションが含まれているかどうかを確認します。サーバーセクションがない場合、システムはエラーメッセージを返し、仕様を無効としてマークします。

    これらの事前定義されたルールは、OpenAPI 仕様のタグ付け、メタデータ、サーバー定義などの重要なセクションを検証します。