SmartDocs の更新

OpenAPI | gRPC

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

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

SmartDocs API リファレンスドキュメント
SmartDocs が OpenAPI ドキュメントの各フィールドを使用して SmartDocs を生成する方法
SmartDocs を再生成する方法

また、それぞれのタスクを実行するために最低限必要な Identity and Access Management のロールについても説明します。IAM の権限について詳しくは、以下をご覧ください。

要件

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

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 を再生成する

このタスクに必要な権限

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

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

OpenAPI ドキュメントを変更します。
OpenAPI ドキュメント（次のコマンドでは openapi.yaml として参照）を再デプロイします。
```
gcloud endpoints services deploy openapi.yaml
```
ポータルページを更新します。

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