SmartDocs の更新

2022 年 3 月 21 日をもって、Cloud Endpoints Portal はサポートが終了しました。2023 年 3 月 21 日以降、Cloud Endpoints Portal は利用できなくなります。Cloud Endpoints が管理する API トラフィックは、この変更の影響を受けません。詳細については、機能のサポート終了をご覧ください。

ポータルの URL を API のユーザーに提供する前に、SmartDocs API リファレンス ドキュメントが正しいこと、API がドキュメントの記述どおりに動作することを確認してください。生成されたリファレンス ドキュメントとテストを確認すると、変更が必要な部分に気づくことがあります。

このページで説明する内容は次のとおりです。

• SmartDocs API リファレンス ドキュメント
• SmartDocs が Cloud Endpoints Frameworks で作成された openapi.json ファイル内のフィールドを使用して SmartDocs を生成する方法
• SmartDocs を再生成する方法。それぞれのタスクを実行するのに最低限必要な Identity and Access Management のロールについても説明します。IAM の権限について詳しくは、以下をご覧ください。
  • ロールについて
  • リソースへのアクセス権の付与、変更、取り消し
  • カスタム役割の作成と管理

要件

このページは、すでにポータルを作成していることを前提としています。

SmartDocs API リファレンス ドキュメントについて

以下の説明に従って API 管理を追加します。

• Java: API 管理の追加
• Python: API 管理の追加

API 用の OpenAPI ドキュメントが Endpoints Frameworks によって作成されます。OpenAPI ドキュメントを Endpoints サービスにデプロイするたびに、SmartDocs によってポータルの API リファレンス ドキュメントが生成されます。SmartDocs UI は、Angular Material という最先端の UI コンポーネント ライブラリに基づいています。デベロッパーは SmartDocs API リファレンス ドキュメントを確認し、その API ドキュメントを表示したまま [この API を試す] ウィジェットを使って API を操作できます。

SmartDocs を生成するために使用される項目について

以下の説明に従って API 管理を追加します。

• Java: API 管理の追加
• Python: API 管理の追加

API 用の JSON 形式の OpenAPI ドキュメントが Endpoints Frameworks によって作成されます。gcloud endpoints services deploy を使用して OpenAPI ドキュメントをデプロイすると、SmartDocs によって Endpoints Frameworks が作成した OpenAPI ドキュメントに基づいて、ポータルの更新 API リファレンス ドキュメントが生成されます。

Endpoints Frameworks は、API 用に作成する OpenAPI ドキュメントに説明を組み込みません。API のユーザーにポータルの URL を提供する前に、OpenAPI ドキュメントの API、メソッド、パラメータに説明を追加することをおすすめします。

OpenAPI を初めて使用する場合は、Swagger basic structure ウェブサイトをご覧ください。このサイトには、サンプル OpenAPI ドキュメントが用意されており、ファイルの各セクションの簡単な説明があります。詳しくは、OpenAPI の仕様をご覧ください。

メタデータのセクションで説明されているように、description フィールドの値には複数の行を含められます。また、このフィールドは GitHub Flavored Markdown をサポートしています。

ユーザーが API のメソッドの使用方法を理解しやすくなるように、パラメータ セクションとリクエスト本文に description フィールドを追加することをおすすめします。

OpenAPI ドキュメントには、次のような内容が含まれています。

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

これらのフィールドの値は、ポータルでは次のように表示されます。

• title: ポータル ホームページでは、title の値が、プロジェクト内の API を一覧表示するセクション、API のホームページ（値の末尾に「documentation」という語が付加された形）、API のタイトルバーに表示されます。

• host: ポータル ホームページでは、host の値（Endpoints サービス名でもあります）が、プロジェクト内の API を一覧表示するセクション、[設定] ページの [API] タブに示されるプルダウン リスト内に表示されます。

• version: メジャー バージョン番号は、API ポータルの URL で使用されます。

title フィールドの値を変更し、API の description フィールドを追加できます。例:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

SmartDocs を再生成する

このタスクに必要な権限

SmartDocs を再生成するには、更新された Endpoints 構成をデプロイします。サービスに関して付与される Service Config 編集者のロールには、Endpoints 構成を再デプロイするのに必要な最小限の権限が含まれています。このロールを割り当てる方法については、API へのアクセス権の付与と取り消しをご覧ください。

リファレンス ドキュメントを再生成するには:

1. Endpoints Frameworks で生成した openapi.json ファイルを変更します。

2. openapi.json を再デプロイします。

   gcloud endpoints services deploy openapi.json
   

3. ポータルページを更新します。

4. 後で openapi.json ファイルの再生成が必要になった場合に、変更した openapi.json ファイルを、上書きされない場所に保存します。API に変更を加えて openapi.json ファイルを再生成する場合は、新しく再生成された openapi.json 内の変更と前に行った変更をマージする必要があります。

このコマンドの詳細については、gcloud endpoints services deploy をご覧ください。