SmartDocs の更新

ポータルの 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 を再生成する

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

  1. OpenAPI ドキュメントを変更します。

  2. OpenAPI ドキュメント(次のコマンドでは openapi.yaml として参照)を再デプロイします。

    gcloud endpoints services deploy openapi.yaml
    
  3. ポータルページを更新します。

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