ポータルの URL を API のユーザーに提供する前に、SmartDocs API リファレンス ドキュメントが正しいこと、API がドキュメントの記述どおりに動作することを確認してください。生成されたリファレンス ドキュメントとテストを確認すると、変更が必要な部分に気づくことがあります。
このページで説明する内容は次のとおりです。- SmartDocs API リファレンス ドキュメント
- SmartDocs が OpenAPI ドキュメントの各フィールドを使用して SmartDocs を生成する方法
- SmartDocs を再生成する方法
要件
このページは、すでにポータルを作成していることを前提としています。
SmartDocs API リファレンス ドキュメントについて
OpenAPI ドキュメントを Endpoints サービスにデプロイするたびに、SmartDocs はポータルの API リファレンス ドキュメントを生成します。SmartDocs UI は、Angular Material という最先端の UI コンポーネント ライブラリに基づいています。デベロッパーは SmartDocs API リファレンス ドキュメントを確認し、その API ドキュメントを表示したまま [この API を試す] パネルを使って API を操作できます。SmartDocs を生成するために使用される項目について
OpenAPI ドキュメントには、たとえば次のような内容が含まれます。
swagger: "2.0" info: description: "A simple Google Cloud Endpoints API example." title: "Endpoints Example" version: "1.0.0" host: "echo-api.endpoints.example-project-12345.cloud.goog"
これらのフィールドの値は、ポータルでは次のように表示されます。
title
: ポータル ホームページでは、title の値が、プロジェクト内の API を一覧表示するセクション、API のホームページ(値の末尾に「documentation」という語が付加された形)、API のタイトルバーに表示されます。description
: description の値は、API ホームページのタイトルの下に小さなフォントで表示されます。host
: ポータル ホームページでは、host の値(Endpoints サービス名でもあります)が、プロジェクト内の API を一覧表示するセクション、[設定] ページの [API] タブに示されるプルダウン リスト内に表示されます。version
: メジャー バージョン番号は、API ポータルの URL で使用されます。
Endpoints Portal では、OpenAPI ドキュメントの paths
セクションにリストされている個々のエンドポイントごとにリファレンス ドキュメントが生成されます。次に示すのは、OpenAPI ドキュメントからの抜粋です。OpenAPI ドキュメントは、Endpoints Portal のデモにある Endpoints Example API の echo
エンドポイント用のリファレンス ドキュメントを生成するのに使用されるものです。
paths: "/echo": post: description: "Echo back a given message." operationId: "echo" produces: - "application/json" responses: 200: description: "Echo" schema: $ref: "#/definitions/echoMessage" parameters: - description: "Message to echo" in: body name: message required: true schema: $ref: "#/definitions/echoMessage" security: - api_key: []
echo
エンドポイントのパラメータは次のセクションで定義されます。
definitions: echoMessage: type: "object" properties: message: type: "string"
Endpoints Portal のデモで使用される完全な openapi.yaml
ファイルは、getting-started
Endpoints サンプルにあります。
ベスト プラクティスとして、プロパティ定義の中、および OpenAPI ドキュメントの他のすべてのセクションの中に、常に description
フィールドを含めてください。description
フィールドには複数の行を含められます。また、このフィールドは GitHub Flavored Markdown をサポートしています。たとえば、次の例ではポータル内の API ホームページに箇条書きリストが作成されます。
swagger: "2.0" info: description: "A simple API to help you learn about Cloud Endpoints. * item 1 * item 2" title: "Endpoints Example" version: "1.0.0" host: "echo-api.endpoints.example-project-12345.cloud.goog"
SmartDocs を再生成する
リファレンス ドキュメントを再生成するには:
OpenAPI ドキュメントを変更します。
OpenAPI ドキュメント(次のコマンドでは
openapi.yaml
として参照)を再デプロイします。gcloud endpoints services deploy openapi.yaml
ポータルページを更新します。
このコマンドの詳細については、gcloud endpoints services deploy
をご覧ください。