SmartDocs を使用した API のドキュメント化

SmartDocs では、完全な対話型の API ドキュメントを Drupal 7 デベロッパー ポータルに作成できます。対話型のドキュメントにより、ポータル ユーザーは次の操作が可能になります。

  • API に関する情報の読み取り
  • API へのライブ リクエストの送信
  • API からのライブ レスポンスの表示

API に関する対話型ドキュメントを作成することで、API の確認、テスト、評価をポータル ユーザーが簡単に行うことができます。

Edge 管理 API は、任意の HTTP クライアントを使用して API サービスにアクセスできる RESTful API です。Apigee では、SmartDocs を使用して、Edge 管理 API の対話型ドキュメントを作成します。この API ドキュメントについては、こちらをご覧ください。

SmartDocs ポータルの例

SmartDocs を使用するには、Apigee Developer Services ポータルが必要です。詳細については、デベロッパー ポータルの作成をご覧ください。

デベロッパー ポータルのホームページで、上部のナビゲーション バーにある [APIs] をクリックして [API Documentation] ページを表示します。

ポータルには、Hello World API と Pet Store Example API の 2 つの API のドキュメントが作成されています。

Hello World API は、疑似ターゲット OpenAPI 仕様の mocktarget.yaml から作成されています。詳細については、https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi をご覧ください。

Pet Store Example API は、従来のペットショップのデモから作成されています。

Hello World API を見てみましょう。

  1. [Hello World API] をクリックします。Hello World API の概要ページが表示されます。
  2. [View API affirmation] をクリックします。このリソースの SmartDocs が表示されます。
  3. [Send this request] をクリックします。
  4. 返されたレスポンスを表示します。
        HTTP/1.1 200 OK
        Connection:
        keep-alive
        Content-Length:
        18
        Content-Type:
        text/html; charset=utf-8
        Date:
        Tue, 21 Jun 2016 21:49:32 GMT
        ETag:
        W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
        X-Powered-By:
        Apigee
        <H2>I <3 APIs</H2>
        
  5. [Request] タブをクリックしてリクエストを表示するか、[cURL] タブをクリックして対応する cURL 呼び出しを表示します。

SmartDocs を使用して API をドキュメント化する方法

SmartDocs は、モデルを使用して API を表します。モデルには、API に関するすべての情報が含まれます。ポータルでは、API に関する情報をモデルから抽出して、Drupal ノードとして、ドキュメントのページをポータルにレンダリングします。各 Drupal ノードは、ポータルのドキュメントのそれぞれのページに対応します。

SmartDocs を使用する場合の一般的な手順は次のとおりです。

  1. Drupal SmartDocs モジュールをポータルに構成します。
  2. SmartDocs モデルを作成します。
  3. WADL ファイルまたは OpenAPI(旧 Swagger)仕様から、あるいは手動で API をモデルに追加します。
  4. モデルを Drupal ノードのコレクションとしてレンダリングします。各 Drupal ノードには、単一の API に関する情報が含まれます。たとえば、API のリソースが POST と PUT の両方のリクエストをサポートしている場合、SmartDocs では個別の Drupal ノードが POST と PUT に作成されます。
  5. Drupal ノードを公開します。公開されると、ポータル ユーザーは API を表示して操作できます。
  6. Drupal ノードを公開する前または公開した後に、それらのノードを編集します。Drupal ノードを編集するには、Drupal エディタを使用するか、元の WADL ファイルまたは OpenAPI 仕様を編集します。WADL ファイルまたは OpenAPI 仕様の編集が完了したら、新しいリビジョンとしてモデルにインポートしてから、変更内容をレンダリングして公開します。
  7. TLS を有効化します。SmartDocs では、API へのリクエストの一部として認証情報をバックエンドに送信できるため、その認証情報の安全性を確保するには、ポータルで TLS を有効にする必要があります。ポータルの本番環境とテスト環境では、https:// リクエストに必要な TLS 証明書が Apigee から提供されますが、ポータルを稼働する前に、独自の TLS 証明書を取得し、TLS を有効にする必要があります。詳細については、ポータルでの TLS の使用をご覧ください。

SmartDoc のモデルとテンプレートについて

モデルをポータルに作成すると、モデルは Drupal ではなく Edge 組織に実際に格納されます。モデルは、内部名("my-smartdocs-api" など)を持つ JSON の大きいブロックで、API の構造を定義します。これに対し、ポータルでは、モデルが HTML でレンダリングされ、モデルの編集インターフェースが提供されます。ポータルで API を更新すると、更新内容がソースモデルに自動的に push されて反映されます。

組織内に格納

Drupal 内に格納

モデル

テンプレート

編集機能を備えた Drupal ノード

複数のポータルが組織内にあるとします(例: dev、stage、production)。Pantheon で、ポータルをある環境から別の環境に移行します。ポータルの各インスタンスには独自のモデルがあるように見えますが、実際には、すべてのインスタンスがソースモデルを参照しています。dev で API を編集すると、モデルが更新され、変更内容が production に表示されます。同様に、dev でモデルを削除すると、ソースが削除され、production で使用できなくなります。

テンプレートでは、SmartDocs の外観を制御します。これらのテンプレート(Handlebars および CSS ファイルで管理)は各ポータルインスタンスとともに格納されます。このため、理論的には、各ポータルでモデルごとに一意のテンプレートが使用されますが、レンダリング フレームワークの便利な点の 1 つは、デフォルトのテンプレート(Apigee のデフォルトのテンプレートまたは指定したテンプレートのいずれか)が各ポータルに自動的に適用されることです。

次の図は、モデルとポータルの関係を示しています。緑色の矢印は自動同期を表します。

次の cURL コマンドを実行すると、組織内のすべてのモデルが一覧表示されます。

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

SmartDocs モジュールの構成

Apigee では、SmartDocs をカスタム Drupal モジュールとして実装しています。SmartDocs モジュールを構成するには、次の手順を使用します。

SmartDocs モジュールを構成するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Modules] を選択します。インストールされているすべての Drupal モジュールのリストが表示されます。
  3. [SmartDocs] モジュールを有効にします。
  4. 構成を保存します。
  5. Drupal の管理メニューで、[Modules] を選択します。
  6. [SmartDocs] -> [Permissions] を選択し、[Administrator] 役割で [Perform administration tasks for the SmartDocs module] が有効になっていることを確認します。
  7. Drupal の管理メニューで、[Configuration] > [Dev Portal] を選択します。
  8. [Connection Timeout] と [Request Timeout] を 16 秒に設定します。
  9. 構成を保存します。
  10. URL 設定を構成します。
    1. Drupal のメニューで、[Configuration] > [Search and metadata] > [URL aliases] > [Settings] を選択します。
    2. [Maximum alias length] と [Maximum component length] を 255 に設定します。
    3. [Punctuation] を展開します。
    4. [Left curly bracket ({)] と [Right curly bracket (})] の設定で、[No action (do not replace)] を選択します。
    5. [Save configuration] をクリックします。
  11. インターネットにアクセスできない内部ネットワーク内のユーザーにデベロッパー ポータルを公開する場合、または API のサブセットがプライベート ネットワーク上にある場合は、SmartDocs API プロキシ URL を次の手順で構成します。
    1. Drupal の管理メニューで、[Configuration] > [SmartDocs] を選択します。
    2. [Advanced Settings] を展開します。
    3. [SmartDocs proxy URL] 項目を次のように更新します。<host>/smartdocs/v1/sendrequest
      お使いの環境に必要な値がインライン ヘルプに表示されます。次に例を示します。
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      この項目のデフォルトは https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest です。
    4. [Save configuration] をクリックします。

モデルの作成

モデルには、API の表現に関するすべての情報が含まれています。複数のモデルをポータルに定義してさまざまな API をサポートしたり、すべての API を単一のモデルにグループ化したりできます。

各モデルでは、生成される Drupal ノードのベース URL も定義する一意の内部名を指定します。各 Drupal ノードの URL の形式は次のとおりです。

    http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>
    

ここで

  • drupalBasePath: ポータルのベース URL。
  • internalName: モデルの内部名。
  • httpMethod: API の HTTP メソッド(get、put、post、delete など)。
  • resourcePath: リソースパス。

たとえば、内部名を「mymodel」として指定した場合、「/books」という名前のリソースに対する GET リクエストについて生成される Drupal ノードの URL は次のようになります。

    http://prod-myco.devportal.apigee.com/mymodel/apis/get/books
    

モデルを作成するには

モデルを作成すると、API 構造のソースとして Edge 組織に格納されます。詳細については、SmartDoc のモデルとテンプレートについてをご覧ください。

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. ページの上部にある [New model] を選択します。
  4. 次の項目を入力します。
    • Name: サイト全体で表示されるモデル名。
    • Internal name: [Name] に入力すると、内部名が表示されます。モデルの内部名は、すべてのモデル間で一意にする必要があります。内部名には、小文字、数字、ハイフン (空白なし) のみを使用してください。この名前を編集するには、[Edit] を選択します。
    • Description: モデルの説明。
  5. [Create Model] を選択します。

モデルを作成すると、モデルのページにリダイレクトされます。そのページから、[Operations] プルダウン ボックスを使用して、次の操作を行うことができます。

  • Import: API を記述する WADL ファイルをインポートするか、API を記述する OpenAPI 仕様の URL を指定します。
  • Add Revision: モデルにリビジョンを追加します。
  • Settings: モデルで使用されるスタイルシートなど、モデルの設定を変更します。
  • Export: モデルをファイルにエクスポートします。
  • Delete: モデルを削除します。

モデルへの API の追加

API をモデルに追加するには、次の方法があります。

  • API 定義が含まれる WADL ファイルをインポートする
  • OpenAPI 仕様(OpenAPI 2.0 または 1.2)をインポートする
  • リソースとメソッドを手動で作成する

SmartDocs JSON ファイルをモデルにインポートすることもできます。このファイルは通常、最初に既存のモデルをエクスポートし、ファイルを編集した後、更新内容をインポートして作成します。詳細については、後述の「モデルのエクスポートとインポート」をご覧ください。

動画: OpenAPI 仕様をインポートして API を SmartDocs モデルに追加する方法を解説する短い動画をご覧ください。

WADL のインポート

モデルを作成したら、API を記述する WADL ファイルをインポートします。WADL ファイルをインポートするたびに、モデルの新しいリビジョンが自動的に作成されます。

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルを選択します。
  4. [Operations] で [Import] を選択します。
  5. SmartDocs インポート ページの [Choose Format] プルダウンで [WADL] を選択します。
  6. [Upload Type] プルダウンで [File] または [URL] を選択します。
    1. [File] を選択した場合は、WADL ファイルを参照します。
    2. [URL] を選択した場合は、WADL ファイルの URL を指定します。
  7. [Import] をクリックして、モデルにインポートします。これで、モデルをレンダリングできます。
  8. モデルの情報ページにリダイレクトされます。このページでモデルをレンダリングできます。

OpenAPI 仕様のインポート

モデルを作成したら、OpenAPI(旧 Swagger)仕様をインポートできます。Edge では、OpenAPI バージョン 1.2 および 2.0 がサポートされています。

OpenAPI では、JSON オブジェクトを含むファイルを使用して API を記述します。OpenAPI 仕様をインポートするたびに、モデルの新しいリビジョンが自動的に作成されます。

OpenAPI 仕様をインポートするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルを選択します。
  4. [Operations] で [Import] を選択します。
  5. SmartDocs インポート ページの [Choose Format] プルダウンで [Swagger JSON] または [Swagger YAML] を選択します。
  6. [Upload Type] プルダウンで [File] または [URL] を選択します(OpenAPI 1.2 については [URL] を選択する必要があります)。
    1. [File] を選択した場合は、OpenAPI 仕様を参照します。
    2. [URL] を選択した場合は、OpenAPI 仕様の URL を指定します。
  7. [Import] をクリックして、モデルにインポートします。
  8. モデルの情報ページにリダイレクトされます。このページでモデルをレンダリングできます。

手動によるリソースとメソッドの作成

API を表現する WADL ファイルまたは OpenAPI 仕様がない場合は、API を手動でモデルに追加できます。また、WADL ファイルまたは OpenAPI 仕様を使用してモデルを作成する場合は、次の手順を使用して、インポート後に API を編集できます(新しい API の追加も含む)。

API を手動で追加するには:

  1. モデルの新しいリビジョンを作成します。

    リビジョンを作成する場合は、モデルのすべての API の単一のベースパスを指定します。これにより、モデルのすべての API で同じベースパスが共有されます。たとえば、ベースパスを次のように指定します。

    https://myCompany.com/v1

    リソースをモデルに追加すると、ベースパスが拡張されます。
  2. 1 つ以上のリソースをモデルに定義します。リソースパスがモデル リビジョンのベースパスと結合されて、リソースの完全な URL が指定されます。たとえば、リソースに「/login」というパスを定義した場合、リソースの完全な URL は次のようになります。

    https://myCompany.com/v1/login
  3. リソースごとに 1 つ以上のメソッドを定義します。メソッドでは、リソースで呼び出すことができる HTTP 動詞を指定します。たとえば、「/login」リソースでは、ログインに POST、ログアウトに DELETE をサポートします。このリソースでは、PUT や GET などの他の HTTP 動詞はサポートしません。したがって、このリソースには 2 つのメソッド(POST に 1 つと DELETE に 1 つ)を定義します。

    メソッドでは、親リソースのリソース URL が使用されます。そのため、同じ URL を持つすべてのメソッドが SmartDocs の単一のリソース下に定義されます。

一般的なルールは次のとおりです。

  • API の一意のベースパスごとに、異なる SmartDocs モデルを作成します。
  • API の一意のリソースごとに、異なる SmartDocs リソースを定義します。
  • リソースでサポートされる HTTP 動詞ごとに、異なる SmartDocs メソッドを定義します。

モデルの新しいリビジョンの作成

リソースは、モデルの既存のリビジョンにのみ追加できます。モデルにすでにリビジョンがある場合、リソースを追加できます。モデルが新しく、リビジョンがない場合は、新しいリビジョンを作成します。

モデルの新しいリビジョンを作成するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [Add Revision] を選択します。
  4. [Add API Revision] ページで、次の情報を入力します。
    • Display Name: ポータルに表示されるリビジョンの名前。
    • Version ID: リビジョンの短い識別子。
    • Description: リビジョンの説明。
    • Base URL: モデルのリビジョンのすべての API のベース URL。モデルでは、リビジョンごとに異なるベース URL を使用できます。たとえば、バージョン インジケータをベース URL に含めます。最初のモデル リビジョンでは、ベース URL は次のとおりです。
      https://myCompany.com/v1
      次のリビジョンでは、ベース URL は次のようになります。
      https://myCompany.com/v2
  5. [Add Revision] を選択します。モデルのリビジョン ページにリダイレクトされます。これで、モデルにリソースを定義できます。

リソースの定義

リソースでは、API の完全な URL を指定します。リソースを定義する際には、リソースパスを指定します。これがモデル リビジョンのベース URL と結合されて、リソースの完全な URL が作成されます。

リソースを定義するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [API Revisions] を選択して、モデルのすべてのリビジョンを表示します。
  4. 編集するリビジョンを選択します。
  5. リビジョン ページで、プルダウン メニューから [Add Resource] を選択します。
  6. [Add Resource] ページで、次の情報を入力します。
    • Display Name: リソースの名前。
    • Path: 「/」で始まるリソースパス。[Path] の値がモデル リビジョンのベース URL と結合されて、リソースの完全な URL が作成されます。
    • Description: リソースの説明。
    • Parameters: 必要に応じて、リソースの各パラメータを定義する JSON オブジェクトを入力します。これらのパラメータについては後述します。
  7. [Add Resource] を選択します。モデルページにリダイレクトされます。これで、リソースにメソッドを定義できます。

必要に応じて、テンプレート パラメータ、クエリ パラメータ、ヘッダー パラメータなどのパラメータをリソースに追加できます。リソース パラメータはすべて、そのリソースに定義するメソッドに継承されます。そのため、クエリ パラメータをリソースに定義した場合は、そのリソースに追加するすべてのメソッドでそのクエリ パラメータがサポートされている必要があります。

また、パラメータをメソッドに定義することもできます。たとえば、POST メソッドでは、DELETE メソッドでサポートされていないクエリ パラメータがサポートされていることがあります。そのため、メソッドを定義する際には、後述のように、メソッドに固有のパラメータを追加します。

次の図は、Apigee Approve or Revoke Developer App API の既存の SmartDocs ページを示しています。パラメータの各タイプをハイライト表示しています。

各パラメータ タイプは JSON オブジェクトによって定義されます。

タイプ

JSON オブジェクト

テンプレート

{
"dataType": "string",
"defaultValue": "",
"description": "The organization name.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

テンプレート パラメータは常に必須であるため、requiredtrue に設定し、defaultValue の値を省略します。

description の値は、ユーザーが SmartDocs ページで URL にカーソルを合わせるとポップアップに表示されます。

クエリ

{
"dataType": "string",
"defaultValue": "",
"description": "The location.",
"name": "w",
"required": true,
"type": "QUERY"
}

必須のクエリ パラメータでも defaultValue を指定できますが、指定することはあまりありません。

省略可能なクエリ パラメータについては、requiredfalse に設定し、defaultValue の値を指定します。

ヘッダー

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Specify as <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": "HEADER"
}

説明で HTML タグの使用方法を確認してください。

テンプレート パラメータでは、リソースパスの変数を定義します。 たとえば、2 つのテンプレート パラメータをリソースに定義するとします。パラメータ配列の各パラメータ定義がカンマでどのように区切られるかに注意してください。

    [
     {
      "dataType": "string",
      "defaultValue": "",
      "description": "Mention the organization name.",
      "name": "org_name",
      "required": true,
      "type": "TEMPLATE"
     },
     {
      "dataType": "string",
      "defaultValue": "",
      "description": "Mention the user email.",
      "name": "developer_email",
      "required": true,
      "type": "TEMPLATE"
     }
    ]
    

これらのテンプレート パラメータを「{}」で囲んで、リソースパス定義で使用できます。たとえば、パスを次のように設定します。

    /login/{org_name}/{developer_email}
    

ユーザーは、SmartDocs API ページでリクエストを送信する前に URL を編集して、URL の org_namedeveloper_email の部分を指定する必要があります。

メソッドの定義

リソースごとに 1 つ以上のメソッドを定義します。メソッド定義では、リソースで呼び出すことができる HTTP 動詞を指定します。1 つのリソースに 1 つのメソッドを定義することも、複数のメソッドを定義することもできます。

メソッド定義の一部として、クエリ パラメータやヘッダー パラメータなど、メソッドで使用されるパラメータを指定します。メソッドへのパラメータの追加については、リソースに関する前述の説明をご覧ください。

次の図は、Apigee Create Developer API の既存の SmartDocs ページを示しています。ページの各領域を、メソッドの定義時に設定する対応する値でハイライト表示しています。

次の図も同じページを示していますが、[Request Body] の [Description] が選択されています。

メソッドを定義するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [API Revisions] を選択して、モデルのすべてのリビジョンを表示します。
  4. 編集するリビジョンを選択します。
  5. リビジョン ページで、いずれかのリソースのプルダウン メニューから [Add Method] を選択します。
  6. [Edit Method] ページで、次の情報を入力します。
    • Display Name: API の名前。API の Drupal ページのタイトルにもなります。
    • Description: API について説明します。
    • Method Verb: HTTP 動詞タイプ。
    • Security Schemes: メソッドの認証モード(ある場合)を指定します。詳細については、SmartDocs 認証タイプの構成をご覧ください。
    • Content Type: リクエストとレスポンスのコンテンツ タイプ。各種の認証方法の構成については、後述のセクションをご覧ください。
    • Parameters: (省略可能)メソッドのクエリ パラメータまたはヘッダー パラメータ。詳細については、リソースへのパラメータの追加に関する前述の説明をご覧ください。
    • Request Body Documentation: (省略可能)リクエスト本文について説明します。POST メソッドと PUT メソッドはリクエスト本文を受け取ります。この領域を使用して説明できます。この値を省略すると、生成される SmartDocs ページから [Request Body] の [Description] リンクが削除されます。
    • Request Body Example: (省略可能)通常は JSON オブジェクトまたは XML としてリクエスト本文の例を示します。POST 動詞と PUT 動詞については、[Request Body Example] が各リクエストの一部として渡されます。SmartDocs ページのユーザーは、API にリクエストを送信する前にこの例を編集します。この値を省略すると、生成される SmartDocs ページから [Request Body] の [Value] リンクが削除されます。
    • Tags: API に関連付けられるタグの配列。SmartDocs では、タグを使用して、類似する API がグループ化されます。たとえば、統計に関するすべての API にタグ「Statistics」を適用できます。異なるリソースの API すべてで同じタグが使用されている場合、それらの API を 1 つのタグでグループ化できます。
  7. [Add Method] を選択します。モデルページにリダイレクトされます。これで、メソッドをレンダリングして公開できます。

モデルのレンダリング

API をモデルに追加したら、モデルをレンダリングできます。レンダリングにより、モデルの API の記述が Drupal ノードに変換されます。レンダリングが完了すると、API ごとに Drupal ノードが 1 つずつ作成されます。各 Drupal ノードは HTML ページに対応します。

モデル全体を一度にレンダリングすることも、個々の API を選択してレンダリングすることもできます。

モデルをレンダリングするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. レンダリングするモデルについて、[Operations] で [API Revisions] を選択します。
  4. レンダリングするリビジョンを選択します。モデルの 1 つのリビジョンからのみノードをレンダリングできます。
  5. レンダリングするメソッドを選択します。
  6. [Update options] プルダウンから [Render Nodes] を選択します。
  7. [Update] をクリックします。
  8. 読み込み中の画面が表示されて、ノードの読み込みの進行状況が示されます。
    ノードがレンダリングされると、各 API に対応する Drupal ノードの ID がモデルの [Node Association] 列に表示されます。[Node Association] 列のリンクをクリックすると、レンダリングされたノードが表示されます。

[Render Nodes] を選択する代わりに [Render and publish nodes] を選択すると、API をレンダリングして、すぐに Drupal ノードとして公開できます。

ノードの公開

ノードは、公開されるまでポータル ユーザーに表示されません。レンダリング プロセス中に、必要に応じてノードの公開を選択できます。ノードの公開を選択しなかった場合は、レンダリングが完了した後に手動で公開する必要があります。

ノードを公開するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 公開するモデルについて、[Operations] で [API Revisions] を選択します。
  4. 公開するリビジョンを選択します。モデルの 1 つのリビジョンからのみノードを公開できます。
  5. 公開するメソッドを選択します。
  6. 公開するリビジョン内のノードを選択します。
  7. [Update options] プルダウンから [Publish Nodes] を選択します。
  8. [Update] をクリックします。
  9. [Node Association] 列でノード ID を選択して、ノードに移動します。

公開済み API ノードへの Drupal URL は、デフォルトで http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath> の形式になります。URL の形式を制御するには、次の手順に従います。

  1. 管理者またはコンテンツ作成特権を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Configuration] > [Search and metadata] > [URL aliases] > [Patterns] を選択します。
  3. [Pattern for all SmartDocs Method paths] で、パスを生成する方法を指定します。
  4. [Save configuration] を選択します。

ポータルでのキャッシュ処理のために、公開後すぐにはモデルページが表示されないことがあります。必要に応じて、次の手順で SmartDocs HTML キャッシュを手動で削除できます。

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Configuration] > [SmartDocs] を選択します。
  3. [Rebuild SmartDocs model caches] をクリックします。

ノードの公開停止

公開済みのノードをいつでも公開停止できます。ノードの公開を停止すると、ポータル ユーザーに表示されなくなります。

ノードの公開を停止するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 公開を停止するモデルについて、[Operations] で [API Revisions] を選択します。
  4. 公開を停止するノードのモデル リビジョンを選択します。
  5. 公開を停止するリビジョン内のノードを選択します。
  6. [Update options] プルダウンから [Unpublish Nodes] を選択します。
  7. [Update] をクリックします。

モデルのリビジョンの表示

新しい WADL ファイルまたは OpenAPI 仕様を既存のモデルにインポートするか、新しいリビジョンを手動で作成して、モデルの新しいリビジョンを作成します。新しいリビジョンを作成したら、リビジョンをレンダリングして公開できます。これにより、現在公開されている Drupal ノードが置き換えられます。

複数のリビジョンからノードを同時にレンダリングして公開できます。つまり、モデルのリビジョンが 5 つある場合、任意のリビジョンからノードを公開することも、すべてのリビジョンからノードを公開することもできます。ただし、一方のモデル内の API が別のモデルから公開されたノードと同じである場合、その API を公開すると、古いバージョンの API の公開が停止され、最も新しく公開された API の内容に置き換えられます。

モデルのリビジョンを表示するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [API Revisions] を選択します。
  4. 表示するモデル リビジョンを選択します。
  5. 前述の手順でノードをレンダリングして公開します。

ノードの編集

ノードをレンダリングしたら、Drupal エディタを使用して編集できます。たとえば、API の HTTP 動詞や説明を編集したり、API に新しいクエリ パラメータやヘッダー パラメータを追加したりできます。WADL ファイルまたは OpenAPI 仕様から作成されたノードを編集することも、手動で作成したノードを編集することもできます。

また、元の WADL ファイルや OpenAPI 仕様を編集することもできます。編集が完了したら、WADL ファイルまたは OpenAPI 仕様を新しいリビジョンとしてモデルに再びインポートし、前述の手順で変更内容をレンダリングして公開します。

Drupal エディタを使用してノードを編集するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. 編集する API ドキュメントに対応する Drupal ノードを参照します。
  3. [Edit] を選択して Drupal エディタを使用します。
  4. 編集が完了したら、[Update Method] を選択します。

また、SmartDocs モデルからノードを編集することもできます。

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [API Revisions] を選択します。
  4. 公開するモデル リビジョンを選択します。
  5. 編集するメソッドの [Operations] プルダウンで [Edit method] を選択します。

ノードを削除するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 更新するモデルについて、[Operations] で [API Revisions] を選択します。
  4. 公開するモデル リビジョンを選択します。
  5. メソッドの [Operations] プルダウンで [Delete method] を選択します。
    注意: ノードを削除すると、モデルから API も削除されます。ポータル ユーザーに表示されないように単に API の公開を停止し、モデルから削除しない場合は、前述の手順でノードの公開を停止する必要があります。

ポータルには、SmartDocs モデルによってレンダリングされるノードのうち、モデルの有効なメソッドを参照しなくなったものについて情報を表示する組み込みのレポートが用意されています。このレポートにアクセスするには、Drupal のメニューで [Reports] を選択し、[SmartDocs node status] という名前のレポートを選択します。

モデルのエクスポートとインポート

SmartDocs では、既存のモデルをファイルにエクスポートできます。たとえば、本番環境とステージング環境を定義するとします。この場合、SmartDocs の編集をすべてステージング環境で行い、API をリリースする準備が整ったら、ステージング環境のモデルをエクスポートして、本番環境のモデルにインポートします。

モデルをインポートすると、モデルの新しいリビジョンが作成されます。SmartDocs は、モデル内の既存の API とインポートされた API を照合しようとします。SmartDocs で一致が検出されると、既存の API に対応する Drupal ノードが更新されます。SmartDocs で一致が検出されなかった場合は、API の新しい Drupal ノードが作成されます。

たとえば、ID 91 の Drupal ノードに対応する POST API があるとします。モデルをインポートすると、インポートされたモデルの POST API と既存の POST API の間で一致が検出されました。この場合、POST API の更新内容によって Drupal ノード 91 が更新されます。一致が検出されなかった場合は、新しい ID で新しい Drupal ノードが作成されます。

Drupal は、API の次の特性を使用して照合を行います。

  • internalName: モデルの内部名。
  • httpMethod: API の HTTP メソッド(GET、PUT、POST、DELETE など)。
  • resourcePath: リソースパス。
  • query params: API で使用されるクエリ パラメータ。

インポートされた API の 4 つの特性すべてがモデルの既存の API と一致する場合、SmartDocs では既存の Drupal ノードが更新されます。

エクスポートされたモデルは、リソースとメソッドのエントリを含む 1 つの JSON オブジェクトで表されます。これは、エクスポートされたモデルを編集してリソースやメソッドを変更し、モデルを再インポートできることを意味します。JSON オブジェクトを編集する場合、次の項目を変更しないでください。

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

モデルをエクスポートするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. エクスポートするモデルについて、[Operations] で [Export] を選択します。
  4. エクスポート ファイルタイプを [SmartDocs JSON] として選択します。
  5. [Export] をクリックします。
  6. メッセージが表示されたら、ファイルをディスクに保存するか、エディタで開くかを選択します。

モデルをインポートするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. インポートするモデルについて、[Operations] で [Import] を選択します。
  4. [Choose Format] プルダウンで [SmartDocs JSON] を選択します。
  5. [Upload Type] で [File] または [URL] を選択します。
    1. [File] を選択した場合は、JSON ファイルを参照します。
    2. [URL] を選択した場合は、SmartDocs JSON ファイルの URL を指定します。
  6. [Import] をクリックして、モデルにインポートします。
  7. モデルの情報ページにリダイレクトされます。このページでモデルをレンダリングできます。インポートによって、モデルの新しいリビジョンが作成されます。
  8. ノードをレンダリングして公開します。

SmartDocs テンプレートの編集

SmartDocs テンプレートでは、Drupal ノードを画面に表示する方法が定義されています。各 SmartDocs モデルに同じデフォルト テンプレートを使用することも、個々のモデルに使用するテンプレートを手動でカスタマイズすることもできます。

SmartDocs テンプレートには、Handlebars .hbr ファイル、CSS ファイル、JavaScript ファイルとしてコーディングされたテンプレート ファイルが含まれます。Handlebars では、コンテンツの多くは、&123;&123;body}} のような埋め込み Handlebars 式を使用して、変数で駆動されます。既存の Handlebars 式のリストは、ファイル先頭のコメントで指定されます。Handlebars を使用したテンプレートのカスタマイズについては、http://handlebarsjs.com をご覧ください。

以下の各セクションでは、新しいモデルすべてで使用したり、既存のモデルに新しい API をインポートするときに使用したりするカスタム SmartDocs テンプレート ファイルをアップロードする方法、元のデフォルトの SmartDocs テンプレート ファイルを復元する方法、個々のモデル用に SmartDocs テンプレートを変更する方法について説明します。

カスタム SmartDocs テンプレート ファイルのアップロード

カスタム SmartDocs テンプレート ファイルを Handlebars .hbr ファイルとしてアップロードして、新しいモデルを作成したり、既存のモデルに新しい API をインポートしたりするときのデフォルト テンプレートとして使用できます。

カスタム SmartDocs テンプレート ファイルを作成する際の出発点としてデフォルトの SmartDocs テンプレート ファイルを使用する場合は、profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr からコピーをダウンロードできます。

カスタム SmartDocs テンプレート ファイルをアップロードするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Configuration] > [SmartDocs] を選択します。
  3. ページの [Advanced Settings] 領域を展開します。
  4. [Upload customized method template] で、[Choose File] をクリックし、Handlebars .hbr ファイルに移動します。
  5. [Upload] をクリックします。
  6. [Save configuration] をクリックします。

デフォルトの SmartDocs テンプレート ファイルの復元

デフォルトの SmartDocs テンプレート ファイルを復元できます。デフォルトの SmartDocs テンプレート ファイルが復元されると、新しいモデルを作成したり、既存のモデルに新しい API をインポートしたりするときに使用されます。

デフォルトの SmartDocs テンプレート ファイルを復元するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Configuration] > [SmartDocs] を選択します。
  3. ページの [Advanced Settings] 領域を展開します。
  4. [Upload customized method template] で、カスタム SmartDocs テンプレート ファイルの横にある [Remove] をクリックします。
  5. [Save configuration] をクリックします。

個々のモデルの SmartDocs テンプレートの変更

個々のモデルに使用されるテンプレートを変更できます。

個々のモデルのテンプレートを変更するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 編集するモデルについて、[Operations] で [Settings] を選択します。
  4. [Method Template] 領域で、必要に応じてテンプレートを編集します。
  5. [Save template] をクリックします。
  6. Drupal ノードを参照します。ページではテンプレートの変更が反映されています。

SmartDocs 認証タイプの構成

SmartDocs で定義した API はオープンにすることも(アクセス時に認証情報を要求しない)、セキュリティで保護することもできます。セキュリティで保護された API では、API を呼び出すときに認証情報を渡す必要があります。

セキュリティで保護された API のために、SmartDocs は次のタイプの認証をサポートします。

  • Basic 認証 - Basic 認証の認証情報(ユーザー名とパスワードのペア)を渡します。認証情報タイプとして OAuth を使用するように指定していない場合、API はデフォルトで Basic 認証を使用します。
  • OAuth 2.0 - サードパーティのサービス プロバイダがユーザーの認証情報を認証し、ユーザーが API に対する認可を得ていることを確認した後、アクセス トークンを発行します。保護された API に対して SmartDocs リクエストを行うと、SmartDocs でリクエストが構築され、サービス プロバイダに送信されます。その後、サービス プロバイダがトークンを検証し、期限切れになっていないことを確認します。
  • カスタム トークン - トークン値をヘッダーまたはクエリ パラメータとして各リクエストに渡します。

それぞれのタイプの認証について、認証の特性を定義するセキュリティ スキームを作成します。たとえば、カスタム トークン認証のセキュリティ スキームでは、トークンを渡す方法(ヘッダー、クエリ パラメータ、本文パラメータ)とトークンの名前を定義します。 

セキュリティ スキームは、モデルの特定のリビジョンに関連付けられます。したがって、モデルの新しいリビジョンを作成する場合は、そのリビジョンについてセキュリティ スキームを再定義する必要があります。 

WADL ファイルでは、次に示すように、<apigee:authentication> Apigee タグを使用して、API で認証が必要であるかどうかを指定します。

    <method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
        ...
        <apigee:authentication required="true"/>
    </method>
    

API がオープンである場合は、required 属性を false に設定します。

WADL ファイルでは、認証のタイプを指定できないことに注意してください。これを指定するには、Drupal でノードを編集します。WADL ファイルの詳細については、WADL リファレンスをご覧ください。

Drupal の [API] ページには、SmartDocs によって次のボタンが追加されるため、ユーザーは Basic 認証の認証情報を指定できます。

ノードを編集して認証タイプを OAuth に設定すると、次のボタンがページに追加されます。

カスタム トークンの場合は次のボタンが追加されます。

Basic 認証の構成

API で Basic 認証を使用する場合、必要な手順は、モデルの作成に使用する WADL ファイルで <apigee:authentication> タグを指定することだけです。

WADL ファイル以外のソースから作成されたメソッドに Basic 認証を適用するには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
  4. 編集するモデル リビジョンについて、[Operations] で [Security Settings] を選択します。
  5. [Add Security Scheme] を選択します。
  6. セキュリティ スキームの名前を指定します。
  7. [Type] として [Basic] を選択します。
  8. [Submit] を選択します。
  9. モデル内の各メソッドについて、メソッドを編集して [Security Scheme] を基本スキームに設定します。
    1. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
    2. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
    3. 編集するモデル リビジョンについて、[Operations] で [Revision Details] を選択します。
    4. 編集する API について、[Edit Method] を選択します。
    5. API の [Security Scheme] を選択します。
    6. [Save] をクリックして API を保存します。

OAuth 2.0 認証の構成

SmartDocs でデフォルトの Basic 認証ではなく、OAuth 2.0 を使用するようにモデルを構成できます。次の 2 か所で OAuth を構成します。

  1. リビジョンの [Security Settings] で、モデルの各リビジョンのセキュリティ スキームを作成します。
  2. モデルの [Settings] で、モデルの全リビジョンの [Client ID] と [Client Secret] を指定します。

OAuth を有効にするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
  4. 編集するモデル リビジョンについて、[Operations] で [Security Settings] を選択します。
  5. [Add Security Scheme] を選択します。
  6. セキュリティ スキームの名前を指定します。
  7. [Type] として [OAuth 2.0] を選択します。
  8. [Grant Type] を設定します。
  9. [Authorization URL] の各項目に値を入力します。[Authorization URL] は、アクセス トークンの取得に使用されます。
  10. [Authorization Verb] を GET または POST として設定します。
  11. [Access Token URL] に値を入力します。[Access Token URL] は、アクセス トークンのリクエスト トークンを送受信するために使用される URL です。
  12. [Access Token param name] に値を入力します。
  13. [In] を使用して、トークンを渡す方法([Header]、[Query]、または [Body])を指定します。
  14. OAuth の [Scopes] を設定します。
  15. [Submit] を選択します。
  16. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  17. モデルについて、[Operations] プルダウンで [Settings] を選択します。
  18. [Client ID] と [Client Secret] に値を入力します。
  19. [Save template authentication settings] を選択します。
  20. モデル内の各メソッドについて、メソッドを編集して [Security Scheme] を OAuth セキュリティ スキームに設定します。
    1. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
    2. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
    3. 編集するモデル リビジョンについて、[Operations] で [Revision Details] を選択します。
    4. 編集する API について、[Edit Method] を選択します。
    5. API の [Security Scheme] を選択します。
    6. [Save] をクリックして API を保存します。

カスタム トークン認証の構成

カスタム トークン認証を使用するようにモデルを構成できます。

カスタム トークンを有効にするには:

  1. 管理者権限またはコンテンツ作成権限を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  3. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
  4. 編集するモデル リビジョンについて、[Operations] で [Security Settings] を選択します。
  5. [Add Security Scheme] を選択します。
  6. セキュリティ スキームの名前を指定します。
  7. [Type] として [Apikey] を選択します。
  8. トークンを含む [Param Name] を設定します。
  9. [In] を使用して、トークンを渡す方法([Header]、[Query]、または [Body])を指定します。
  10. [Submit] を選択します。
  11. モデル内の各メソッドについて、メソッドを編集して [Security Scheme] をトークン スキームに設定します。
    1. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
    2. 目的のモデルについて、[Operations] で [API Revisions] を選択します。
    3. 編集するモデル リビジョンについて、[Operations] で [Revision Details] を選択します。
    4. 編集する API について、[Edit Method] を選択します。
    5. API の [Security Scheme] を選択します。
    6. [Save] をクリックして API を保存します。

モデルの削除

モデルを削除すると(Drupal で [Content] > [SmartDocs] を選択し、[Operations] 項目で [Delete] を選択する)、Edge 組織からモデルが削除されます。これは、他のポータルがこのモデルを参照している場合、このモデルを使用できなくなることを意味します。詳細については、SmartDoc のモデルとテンプレートについてをご覧ください。