1. Homepage
  2. Exchange
  3. API カタログ CLI を使用した API の自動カタログ化

  4. CLI を使用した記述子ファイルの作成または更新

CLI を使用した記述子ファイルの作成または更新

コマンドを実行して API をパブリッシュする前に、Exchange で API をカタログ化するために必要な情報が含まれる記述子ファイルを作成する必要があります。通常、CLI を使用してファイルを作成し、手動でファイルを更新して、アセットのパブリッシュ方法を制御するためのその他のオプションを設定します。

記述子の出力には、各 API の次の情報が含まれます。

  • API 定義ファイル名

  • アセット ID

  • アセットバージョン

  • API バージョン

記述子ファイルを作成する

api-catalog create-descriptor​ コマンドを使用して、API カタログ記述子 YAML の結果を識別し、指定されたファイルに出力します。このコマンドは、現在の作業ディレクトリに対して相対的な完全なディレクトリツリーで検出されたすべての API 定義のカタログ情報を出力します。

api-catalog create-descriptor

> api-catalog create-descriptor [flags]

このコマンドは、次のフラグを受け入れます。

フラグ 説明

-d, --file=file

デフォルト: catalog.yaml​

生成されたカタログ記述子ファイルを保存する名前と場所。

--external

記述子ファイルに記述されている API ごとに ​exchange.json​ ファイルを生成し、​projects​ セクションの ​ref​ タグを使用して記述子ファイル内の各 API への参照を追加します。

CLI を使用して記述子ファイルを作成する手順は、次のとおりです。

  1. カタログ化する API が含まれるディレクトリパスに移動します。

  2. api-catalog create-descriptor​ コマンドを実行します。次の例では、現在のパスに ​mydescriptor.yaml​ という記述子ファイルを作成します。

    > api-catalog create-descriptor -d mydescriptor.yaml

    記述子ファイルに書き込まれる出力例:

    #%Catalog Descriptor 1.0
projects:
 - main: async-spec.json
  assetId: async-api
  version: 2.0.0
  apiVersion: v2
 - main: codat.json
  assetId: codat-api
  version: 1.0.0
  apiVersion: v1
 - main: oas-3-spec.json
  assetId: oas-3-api
  version: 3.0.0
  apiVersion: v3

    --external​ フラグを使用する場合、次の例のように API ごとに ​exchange.json​ ファイルが生成され、記述子ファイルにそれらの参照が含まれます。

    > api-catalog create-descriptor -d mydescriptor.yaml --external

    記述子ファイルに書き込まれる出力例:

    #%Catalog Descriptor 1.0
projects:
  - ref: api-spec/async-spec.exchange.json
  - ref: api-spec/codat.exchange.json
  - ref: api-spec/oas-3-spec.exchange.json

指定された記述子ファイルのプレゼンスおよびコンテンツは、次のようにコマンドの結果に影響します。

  • ファイルがないか、空のファイル: コマンドは API を検出して、結果を標準出力と、​catalog.yaml​ という名前のファイルに書き込みます。

  • コンテンツがある既存のファイル: コマンドは失敗し、記述子ファイルがすでに存在することを示すエラーメッセージが表示されます。

記述子ファイルを使用したドキュメントページと画像のリンク

記述子にマークダウンファイルを追加することで、ドキュメントページと画像を API に追加できます。Exchange アセット用に作成したドキュメントページに画像を表示できます。

記述子ファイルの例:

#%Catalog Descriptor 1.0
projects:
  - main: sources/api.raml
    documentation:
      - Summary: Summary.md
      - Use Cases: Use_Cases.md
    assetId: version-basic-api
    apiVersion: v4
    version: 4.0.0

画像 (.png、.jpg) へのリンクとドキュメントマークダウンファイルを含む ​Summary.md​ ファイルを使用すると次のようになります。

This is a caching service that can be used to retrieve picklist values from publishers who wish to provide a caching service for their picklist fields.

![muley logo](muleyLogo.png)

[Read all the Use Cases](Use_Cases.md)

指定された記述子ファイルのプレゼンスおよびコンテンツは、次のようにコマンドの結果に影響します。

  • 記述子カタログで参照されているファイルのドキュメントエントリが消えるため、アセットポータルでページ間を移動するためのリンクは機能しません。

記述子ファイルを更新する

api-catalog update-descriptor​ コマンドを使用して、指定されたファイルの API カタログ記述子 YAML の結果を更新します。このコマンドは、現在の作業ディレクトリに対して相対的な完全なディレクトリツリーで検出されたすべての新規および更新された API 定義のカタログ情報を追加/更新します。

このコマンドを使用して、​--external​ フラグで作成された記述子ファイルを更新することはできません。

api-catalog update-descriptor

> api-catalog update-descriptor [flags]

このコマンドは、次のフラグを受け入れます。

フラグ 説明

-d, --descriptor-file=descriptor-file

デフォルト: catalog.yaml​

更新されたカタログ記述子ファイル情報を保存する名前と場所。

CLI を使用して記述子ファイルを更新する手順は、次のとおりです。

  1. カタログ化する API が含まれるディレクトリパスに移動します。

  2. api-catalog update-descriptor​ コマンドを実行します。次の例では、現在のパスの ​mydescriptor.yaml​ という記述子ファイルを更新します。

    > api-catalog update-descriptor -d mydescriptor.yaml

指定された記述子ファイルのプレゼンスおよびコンテンツは、次のようにコマンドの結果に影響します。

  • ファイルがないか、空のファイル: 更新では有効な記述子ファイルが存在している必要があるため、エラーメッセージが表示されます。

  • コンテンツがある既存のファイル: コマンドはディレクトリパスの API と記述子ファイルの API のリストを比較し、新規または更新された API 情報で記述子ファイルを更新します。

  • projects​ セクションに ​ref​ タグがあるファイル: update-descriptor​ コマンドでは、外部 ​exchange.json​ ファイルへの参照がある記述子ファイルはサポートされていないため、コマンドで解析エラーが発生します。

関連情報