SmartDocs の更新

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

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

  • SmartDocs API リファレンス ドキュメント
  • SmartDocs が .proto 内の項目とコメントおよびサービス構成ファイルを使用して SmartDocs を生成する方法
  • SmartDocs を再生成する方法
また、それぞれのタスクを実行するために最低限必要な Identity and Access Management のロールについても説明します。IAM の権限について詳しくは、以下をご覧ください。

要件

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

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

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

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

サービス構成ファイル（api_config.yaml として参照されます）には次のような内容が含まれます。

title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.Bookstore

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

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

Endpoints Portal は、.proto ファイル内の RPC メソッドとリソースごとにリファレンス ドキュメントを生成します。それぞれのメソッドとリソースに関連付けられたコメントは、ポータルに表示されるドキュメントに組み込まれます。次に示すのは、.proto ファイルからの抜粋です。このファイルは、Endpoints Portal のデモで Bookstore gRPC API サンプル用のリファレンス ドキュメントを生成するために使用されます。

service Bookstore {
  // Returns a list of all shelves in the bookstore.
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {}
  // Creates a new shelf in the bookstore.
  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {}
  // Returns a specific bookstore shelf.
  rpc GetShelf(GetShelfRequest) returns (Shelf) {}
  // Deletes a shelf, including all books that are stored on the shelf.
  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {}
  // Returns a list of books on a shelf.
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}
  // Creates a new book.
  rpc CreateBook(CreateBookRequest) returns (Book) {}
  // Returns a specific book.
  rpc GetBook(GetBookRequest) returns (Book) {}
  // Deletes a book from a shelf.
  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {}
}

Endpoints Portal のデモで使用される完全な bookstore.proto ファイルは、bookstore-grpc Endpoints サンプルにあります。

SmartDocs を再生成する

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

  1. サービスの構成や .proto ファイルを変更します。

  2. .proto ファイルを変更した場合は、プロトコル バッファをコンパイルします。

  3. .pb ファイルとサービス構成ファイルを再デプロイします。次に例を示します。

    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

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

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