ポータルの URL を API のユーザーに提供する前に、SmartDocs API リファレンス ドキュメントが正しいこと、API がドキュメントの記述どおりに動作することを確認してください。生成されたリファレンス ドキュメントとテストを確認すると、変更が必要な部分に気づくことがあります。
このページで説明する内容は次のとおりです。- SmartDocs API リファレンス ドキュメント
- SmartDocs が
.proto
内の項目とコメントおよびサービス構成ファイルを使用して SmartDocs を生成する方法 - SmartDocs を再生成する方法
要件
このページは、すでにポータルを作成していることを前提としています。
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 を再生成する
リファレンス ドキュメントを再生成するには:
サービスの構成や
.proto
ファイルを変更します。.proto
ファイルを変更した場合は、プロトコル バッファをコンパイルします。.pb
ファイルとサービス構成ファイルを再デプロイします。次に例を示します。gcloud endpoints services deploy api_descriptor.pb api_config.yaml
ポータルページを更新します。
このコマンドの詳細については、gcloud endpoints services deploy
をご覧ください。