1. Homepage
  2. API Governance
  3. 準拠の問題の検出と修正

  4. 仕様での準拠の問題の検出と修正

仕様での準拠の問題の検出と修正

API Governance コンソールにアクセスできない場合でも、Design Center やガバナンス CLI を使用して、ガバナンスルールセットに対して個々の API 仕様を検証できます。仕様の準拠の問題は API Designer で直接修正できます。

Design Center で API 仕様を検証する

ガバナンスルールセットに対して API を検証するには、Design Center API Designer テキストエディターで API 仕様にルールセットを連動関係として追加します。ルールセットを追加したら、​[Project Errors (プロジェクトエラー)]​ セクションを展開して、準拠メッセージを表示します。

API Designer で連動関係として適用されたルールセットのスクリーンショット
1 API プロジェクトにルールセットを追加します。
2 準拠の問題を表示し、重大度のレベルで絞り込みます。
3 テキストエディターの ​[Project Errors (プロジェクトエラー)]'​ セクションを展開して、非準拠メッセージを表示します。

プロジェクトへのルールセットの追加

API Designer で、API プロジェクトに Exchange 連動関係としてガバナンスルールセットを追加できます。

API が一元化された API Governance の管理対象として識別されている場合、​[Exchange dependencies (Exchange 連動関係)]​ アイコンの上に、このプロジェクトの連動関係に対してアクションを実行する必要があることを示すドットまたは警告アイコンが表示されます。​[Exchange dependencies (Exchange 連動関係)]​ アイコンをクリックし、ルールセットを連動関係としてプロジェクトに追加するための対話型の手順を表示して実行します。

「API 仕様プロジェクトへの連動関係の追加」​を参照してください。

準拠プロジェクトエラーを修正する

API Designer テキストエディターを使用して準拠プロジェクトエラーを修正するには、​「テキストエディターでの API 仕様の作成」​を参照してください。

API Governance CLI を使用してガバナンスルールセットに対して API 仕様を検証する

コマンドを使用してガバナンスルールセットに対して API 仕様を検証する場合は、​governance:api:validate​ コマンドを使用します。

governance:api:validate

> governance:api:validate <api-specification> [フラグ]

このコマンドは、指定されたルールセットに対して ​api-specification​ で渡された API 仕様を検証します。

このコマンドには複数オプションのフラグがあります。コマンドで複数オプションのフラグを使用する場合は、フラグの前にパラメーターを置くか、パラメーターの前に「-- 」(2 つのダッシュの後にスペース) を使用します。

api-specification​ は次のいずれかとして指定できます。

  • API プロジェクト ZIP ファイル

  • API プロジェクトフォルダー

  • --remote​ フラグが指定されている場合は、API プロジェクトのアセット識別子。アセット識別子は、Exchange 内の各アセットを一意に識別するグループ ID、アセット ID、およびバージョン (GAV) です。

検証するルールセットを次のように指定できます。

  • API プロジェクトのルールセットの連動関係を定義する既存の ​exchange.json​ ファイルを使用するには、​api-specification​ で指定したフォルダーまたは ZIP ファイルに ​exchange.json​ ファイルが含まれていることを確認してください。​exchange.json​ ファイルが存在する場合、このコマンドはすべてのルールセット連動関係をダウンロードし、それらのルールセットに対して検証します。ルールセットの連動関係は、API Designer でその API プロジェクトに連動関係が定義されている場合にのみ、​exchange.json​ ファイルに存在します。​「プロジェクトへのルールセットの追加」​を参照してください。

  • Exchange でパブリッシュされているルールセットに対して直接検証するには、​--remote-rulesets​ フラグを使用します。

  • ローカルルールセットに対して検証するには、​---rulesets​ フラグを使用します。

重複するルールセットは検出されないため、同じコマンドの実行でルールセットを特定する前述の方法を複数使用すると、一部のルールセットが複数回検証される場合があります。

このコマンドでは、デフォルトのフラグ以外に次のフラグも受け入れます。

フラグ 説明

--rulesets <ruleset-yaml-file1> <ruleset-yaml-file2> …​

ローカルルールセット定義。​rulesets​ フラグの後には、カンマで区切られたルールセット YAML ファイルのリストが続きます。

--remote-rulesets <ruleset-asset-identifier> <ruleset-asset-identifier> …​

リモートルールセット定義。​remote-rulesets​ フラグの後には、カンマで区切られたルールセットアセット識別子のリストが続きます。アセット識別子は、Exchange 内の各アセットを一意に識別するグループ ID、アセット ID、およびバージョン (GAV) です。例: <group_id>/<asset_id>/<version>,<group_id>/<asset_id>/<version>​

Exchange アセット識別子 (GAV) を取得する​を参照してください。

--remote

パブリッシュされた API に対して検証を行う必要があることを示すフラグ。​api-specification​ で渡される値は、API のアセット識別子です。アセット識別子は、Exchange 内の各アセットを一意に識別するグループ ID、アセット ID、およびバージョン (GAV) です。例: <group_id>/<asset_id>/<version>​

Exchange アセット識別子 (GAV) を取得する​を参照してください。

コマンド例:

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip --rulesets /MyRulesets/ruleset1.yaml /MyRulesets/ruleset2.yaml

anypoint-cli-v4 governance:api:validate /MyApis/order-api-1.0.0-raml.zip --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1

anypoint-cli-v4 governance:api:validate 8a840abd-e63a-4f8b-87ab-24052eda2017/order-api/1.0.0 --remote-rulesets 68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1 --remote

出力例:

ルールセットに適合する仕様の場合:

 Spec conforms with Ruleset

ルールセットに適合しない仕様の場合:

Conforms: false
Number of results: 3 (1)

Functional Validations
----------------------

Constraint: http://a.ml/vocabularies/amf/core#declaration-not-found
Severity: Violation
Message: not supported scalar for documentation
Target: null
Range: [(6,3)-(6,3)]
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml

Conformance Validations (2)
-----------------------

Constraint: file:///exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/anypoint-best-practices/1.0.0/ruleset.yaml#/encodes/validations/api-must-have-documentation (3)
Severity: Warning (4)
Message: Provide the documentation for the API. (5)
Target: amf://id#2 (6)
Range: [(2,0)-(6,4)] (7)
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml (8)

Constraint: file:///exchange_modules/8a840abd-e63a-4f8b-87ab-24052eda2017/best-practices-ruleset/1.0.0/bestpractices.yaml#/encodes/validations/api-must-have-documentation
Severity: Violation
Message: Provide the documentation for the API
Target: amf://id#2
Range: [(2,0)-(6,4)]
Location: file:///Users/myuser/Downloads/order-api-1.0.0-raml/order-api-1.0.0-raml
1 見つかった機能および準拠検証の問題の合計
2 準拠の問題セクション
3 この一連の問題が適用されるルールセットとルール
4 問題の重要度
5 問題の説明
6 AMF モデルノード ID。AMF モデルについての詳細は、​「カスタムガバナンスルールセットの作成」​を参照
7 問題が発生した API 仕様の開始行番号と列および終了行番号と列。ここで、列は行の先頭からのオフセットであり、オフセットの番号は 0 で開始
8 問題が発生したファイル (メインファイルまたはその連動関係のいずれか)

Exchange アセット識別子 (GAV) を取得する

Exchange アセットの GAV を取得するには、次の操作を実行します。

  • Exchange CLI を使用している場合、​exchange:asset:list​ コマンドを実行します。

  • Exchange Web UI を使用している場合、Exchange でアセットを選択し、URL からグループ ID とアセット ID をコピーします。次に、表示しているバージョンのバージョンノードを追加します。たとえば、Exchange の「OpenAPI Best Practices (OpenAPI ベストプラクティス)」ルールセットの GAV は ​68ef9520-24e9-4cf2-b2f5-620025690913/open-api-best-practices/1.0.1​ です。

関連情報