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 ポータルが必要です。詳細については、デベロッパー ポータルの作成をご覧ください。

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

ポータルには、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 の使用をご覧ください。

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] -> [Permission] を選択し、「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] プルダウン ボックスを使用して、次の操作を行うことができます。

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

モデルへの API の追加

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

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

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

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

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: 「/」で始まるリソースパス。パスの値はモデル リビジョンのベース 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"
}

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

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

クエリ

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

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

オプションのクエリ パラメータでは、required を false に設定し、値を 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_name と developer_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 メソッドはリクエスト本文を受け取ります。この領域を使用して説明できます。この値を省略すると、[Request body] の [Description] リンクが、生成される SmartDocs ページから省略されます。
    • Request Body Example:（省略可能）リクエスト本文の例を表示します。通常は、JSON オブジェクトまたは XML として表示されます。POST および PUT 動詞の場合、Request Body Example が各リクエストの一部として渡されます。SmartDocs ページを使用する場合は、API にリクエストを送信する前に、この例を編集します。この値を省略すると、[Request body] の [Value] リンクが、生成される SmartDocs ページから省略されます。
    • 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] を選択します。
  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] をクリックし、Hnadlebars .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 認証 - 基本的な認証資格情報をユーザー名とパスワードのペアとして渡します。資格情報のタイプとして「Oauth」の使用を指定していない場合、API はデフォルトで Basic 認証を使用します。
  • OAuth 2.0 - サードパーティのサービス プロバイダがユーザーの資格情報を認証し、ユーザーが API に対する許可を得ていることを確認して、アクセス トークンを発行します。保護された API に対して SmartDocs リクエストを行うと、SmartDocs でリクエストが構築され、サービス プロバイダに送信されます。その後、サービス プロバイダがトークンを検証し、期限切れになっていないことを確認します。
  • カスタム トークン - トークン値をヘッダーまたはクエリ パラメータとして各リクエストに渡します。

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

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

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

<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. API を保存します。

OAuth 2.0 認証の構成

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

  1. モデルの各リビジョンのセキュリティ スキームを、リビジョンの [Security Settings] で作成します。
  2. モデルのすべてのリビジョンのクライアント ID とクライアント シークレットを、モデルの [Settings] で指定します。

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 のスコープを設定します。
  15. [Submit] を選択します。
  16. Drupal の管理メニューで、[Content] > [SmartDocs] を選択します。
  17. モデルの [Operations] プルダウンで [Settings] を選択します。
  18. [Client ID] と [Client Service] に値を入力します。
  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. 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. API を保存します。

モデルの削除

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