API インサイトでの API 仕様の検証
API 仕様検証ルールにアクセスして、API 仕様が完全で一貫性があり、ベストプラクティスに準拠していることを確認できます。
検証ルールは、インポートまたは分析中に構造的な問題を早期に特定し、API 全体の品質を向上させます。これらのルールを管理して API 仕様全体で標準化を適用し、API を公開または本番環境で使用する前に、欠落しているフィールドや誤ったフィールドをチェックすることでエラーを減らすことができます。
API 仕様の保存
API 仕様 [sn_api_insights_ws_api_specification] テーブルには、個々の API を記述する仕様ドキュメントが格納されます。各レコードには、仕様が属する API を識別し、複数のバージョンを管理するための次の詳細が含まれています。
| フィールド | 説明 |
|---|---|
| 名前 | API の名前。 |
| バージョン | API のバージョンを入力します。 |
| タイプ | 使用されている API 仕様標準の形式とバージョン。たとえば、 OpenAPI 仕様の場合は openapi3.0.0 です。 |
| 状況 | API 仕様が適用可能なルールと検証結果に対して検証されているかどうかを示す現在のステータス。有効な値は次のとおりです。
|
| 仕様 | API 仕様ファイルの完全なコンテンツ。 注: OpenAPI の場合は、エンドポイント、メソッド、およびスキーマについて説明する完全な OpenAPI ドキュメントが含まれています。 |
| メッセージ | メッセージは、仕様タイプのすべての検証ルールを処理した後に生成されます。エラーまたは警告と説明が含まれます。 |
検証ルールの構造
仕様検証ルール [sn_api_insights_ws_spec_validation_rule] テーブルには、API 仕様 [sn_api_insights_ws_api_specification] テーブルで定義された API 仕様の検証ルールが保存されます。
注:
検証ルールを編集または削除するには sn_cmdb_editor ロールが必要であり、検証ルールを表示するには cmdb_read ロールが必要です。
各検証ルールには、次の主要なコンポーネントが含まれています。
| コンポーネント | 説明 |
|---|---|
| 仕様 | ルールが設計された API 仕様。 |
| バージョン | ルールが検証する API 仕様のバージョン。指定した場合、ルールはそれらのバージョンにのみ適用されます。検証を特定のバージョンに制限するには、[ バージョン] フィールドでそのバージョンを指定します。複数の値はカンマで区切ります。例: 1.0,1.1,2.0。注: [ バージョン] フィールドを空のままにすると、指定された API 仕様タイプのインストール済みバージョンすべてに対してルールが実行されます。 |
| タイプ | 実行する検証のタイプ。有効な値は次のとおりです。
|
| キー | 検証する仕様の一部。予期される値が指定されていない場合は、[ キー ] フィールドに複数のキーをカンマで区切って入力できます。 |
| 値 | [ キー ] フィールドで指定されたキーに必要な値。複数の値はカンマで区切ります。 |
| 重大度 | 検証ルール結果の重大度レベル (警告またはエラー)。 注: [警告] に設定すると、ルールが満たされていなくても API 仕様は有効なままになり、エラーではないことが示され、メッセージのみが表示されます。 |
| メッセージ | ルールがトリガーされたときの問題の説明。 |
| アクティブ | ルールをアクティブ化するためのオプションアクティブなルールのみが、 API Specification Validation スケジュール済みジョブによってトリガーされます。 |
API 仕様検証プロセス
API Specification Validationスケジュール済みジョブは、未処理の API 仕様を仕様タイプに基づいてアクティブなルールに対して自動的に検証し、必要な標準への準拠を確認します。
検証プロセスには次のものが含まれます。
- 仕様検証ルール [sn_api_insights_ws_spec_validation_rule] テーブルからすべてのアクティブな検証ルールを取得しています。
- API 仕様 [sn_api_insights_ws_api_specification] テーブルで未処理としてマークされた API を選択します。
- OpenAPI などの仕様タイプに基づいて、選択した各 API に関連する検証ルールを適用します。
- API 仕様内の特定のフィールドまたはその値の存在または正確性を検証します。
- 処理ステータスを更新し、エラーまたは警告をキャプチャします。
OpenAPI 仕様の事前定義されたルール
デフォルトでは、アプリケーションには OpenAPI 仕様の次の検証ルールが含まれています。
- タグを検証
- API 仕様の各タグに
名前フィールドが含まれていることを確認します。[名前] フィールドがない場合、システムは警告メッセージを返しますが、仕様は有効としてマークされます。 - 必須セクションを検証
- API 仕様に必要なトップレベルのセクション (
情報、パス、およびコンポーネント) が含まれていることを確認します。これらのセクションのいずれかが欠落している場合、システムはエラーメッセージを返し、仕様を無効としてマークします。 - [サーバーを検証] セクション
- API 仕様にサーバーエンドポイントを定義する
サーバーセクションが含まれているかどうかを検証します。サーバーセクションがない場合、システムはエラーメッセージを返し、仕様を無効としてマークします。
これらの事前定義されたルールは、OpenAPI 仕様のタグ付け、メタデータ、サーバー定義などの重要なセクションを検証します。