Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

ドキュメント API に対する SmartDocs の使用

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

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

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

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

SmartDocs を使用して API を文書化するために、Display Suite モジュールを無効にする必要があります。SmartDocs と Display Suite モジュールは互換性がありません。Display Suite モジュールの使用は推奨されておらず、将来のリリースで削除される予定です。

SmartDocs ポータルの例

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

From your developer portal home page, click APIs in the top navigation bar to view the API Documentation page.

There are two APIs documented on the portal: Hello World and Pet Store Example.

The Hello World API was created from the mock target OpenAPI Specification, mocktarget.yaml. For more information, see https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi

The Pet Store Example API was created from the classic pet store demo.

Explore the Hello World API:

  1. Click Hello World API. The Hello World API summary page is displayed:
  2. Click View API affirmation. The SmartDocs for this resource is displayed:
  3. Click Send this request.
  4. View the response returned:
    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. Click the Request tab to view the request, or the cURL tab to view the corresponding cURL call.

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

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

SmartDocs を使用して API を文書化するために、Display Suite モジュールを無効にする必要があります。SmartDocs と Display Suite モジュールは互換性がありません。Display Suite モジュールの使用は推奨されておらず、将来のリリースで削除される予定です。

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. Edit the Drupal nodes, either before or after you publish them. You can edit the Drupal nodes by using the Drupal editor or by editing the original WADL file or OpenAPI Specification. When you are done editing the WADL file or OpenAPI Specification, import it back into the model as a new revision, then render and publish your changes.
  7. Enable TLS. Because SmartDocs can send authentication credentials to your backend as part of making a request to your APIs, you should enable TLS on your portal to ensure that those credentials are secure. In the portal production and test environments, Apigee provides the TLS certificate required to make https:// requests. However, before you go live with your portal, you must obtain your own TLS certificate and enable TLS. For more, see Using TLS on the portal.

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

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

組織内に格納

Drupal 内に格納

モデル

テンプレート

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

例えば、複数のポータルが組織 (organization) 内にあるとします (例: dev、stage、production)。Pantheon で、ポータルをある環境 (environment) から別の環境に移行します。ポータルの各インスタンスは独自のモデルを含んでいるように見えますが、実際には、すべてのインスタンスがソースモデルを参照しています。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 モジュールを構成するには、次の手順を使用します。

ポータルを Apigee Edge for the Private Cloud に接続している場合は、Edge のインストール時に SmartDocs が Edge 管理サーバーにインストールされたことを確認する必要があります。詳細については、Apigee Edge for the Private Cloud のドキュメントの『Install and Configuration Guide』を参照してください。

Apigee サポートの指示がない限り、 「SmartDocs configuration」ページ (Drupal の管理メニューの「Configuration」 > 「SmartDocs」を選択すると、表示できます) の「Manage API override settings」セクションの下にある以下の設定を変更しないでください。

  • 「Use Local SmartDocs JS/CSS」 (有効)
  • 「Local SmartDocs JS/CSS version」 (v6)

これらの設定を変更した場合、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. For Public or Private Cloud users working in an environment with restricted or no internet access, configure the SmartDocs API proxy URL, as follows:
    1. Select Configuration > SmartDocs in the Drupal Administration menu.
    2. Expand Advanced Settings.
    3. Update the SmartDocs proxy URL field as follows: <host>:<port>/smartdocs/v1/sendrequest.
      Typically, <host> is the Edge host and <port> is 59001. For example: https://<edgehost>:59001/smartdocs/v1/sendrequest

      This field defaults to 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 メソッド (ge、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 a WADL file describing your API or specify the URL of an OpenAPI Specification that describes your API.
  • モデルにリビジョンを追加する
  • モデルで使用されるスタイルシートなど、モデルの設定を変更する
  • モデルをファイルにエクスポートする
  • モデルを削除する

モデルへの API の追加

API をモデルに追加には、次の操作を実行します。

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

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

WADL のインポート

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

W3C Web サイトの WADL 仕様 (http://www.w3.org/Submission/wadl/) では、WADL に複数の <resources> タグを含めることができるように指定しますが、SmartDocs では、単一の <resources> タグを含む WADL ファイルしか処理できません。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. モデルの情報ページにリダイレクトされ、モデルをレンダリングできます。

Import an OpenAPI Specification

After you have successfully created a model, you can import an OpenAPI (formerly Swagger) Specification. Edge supports OpenAPI version 1.2 and 2.0.

OpenAPI uses files containing JSON objects to describe an API. Every time you import an OpenAPI Specification, you automatically create a new revision of the model.

OpenAPI は、JSON-Schema draft 4 を使用して (JSON ペイロードのような) 複雑なオブジェクトと記述し、スキーマオブジェクトを使用してモデルを記述します。同じスキーマか SmartDocs によって使用されて、API 用のサンプルペイロードを生成します。XML 拡張機能は SmartDocs によってサポートされていません。

Before you import your OpenAPI Specification, you can validate it using one of the following tools:

  • Apigee API Studio
  • swagger-tools
  • Pass the URL of your OpenAPI Specification (openapiURL) to one of the following URLs to validate it: 
    http://online.swagger.io/validator?url=openapiURL
    http://online.swagger.io/validator/debug?url=openapiURL (displays error information)

To import an OpenAPI Specification:

  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. If you select File, browse to the OpenAPI Specification.
    2. If you select URL, specify the URL of the OpenAPI Specification.
  7. 「Import」をクリックして、モデルにインポートします。
  8. モデルの情報ページにリダイレクトされ、モデルをレンダリングできます。

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

If you do not have a WADL file or OpenAPI Specification that represents your API, you can manually add APIs to your model. Also, if you use a WADL file or OpenAPI Specification to create your model, you can use this procedure to edit your APIs, including adding new APIs, after import.

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 と 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。モデルでは、リビジョンごとに異なるベース API を使用できます。例えば、バージョンインジケータをベース URL に含めることができます。最初のモデルリビジョンでは、ベース URL は次のようになります。
      https://myCompany.com/v1
      次のリビジョンでは、ベース URL は次のようになります。
      https://myCompany.com/v2
  5. 「Add Revision」を選択します。モデルのリビジョンページにリダイレクトされます。これで、リソースをモデルに定義できます。

リソースの定義

リソースでは、API の完全な URL を指定します。リソースを定義する場合は、リソースパスを指定します。リソースパスは、モデルリビジョンのベース URL と結合され、リソースの完全な 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 動詞を指定します。リソースには、単一のメソッドを定義したり、複数のメソッドを定義したりできます。

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

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

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

メソッドを定義するには、次の手順に従います。

  1. 管理者またはコンテンツ作成特権を持つユーザーとしてポータルにログインします。
  2. Drupal の管理メニューで、「Content」>「SmartDocs」を選択します。
  3. 更新するモデルで、「Operations」「API Revisions」を選択して、モデルのすべてのリビジョンを表示します。
  4. 編集するリビジョンを選択します。
  5. リビジョンページで、リソースの 1 つのドロップダウンメニューから「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 を単一のタグにグループ化できます。
  7. 「Add Method」を選択します。モデルページにリダイレクトされます。これで、メソッドをレンダリングして公開できます。

モデルのレンダリング

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

モデル全体の一括レンダリング、または個々の API のレンダリングを選択できます。  

モデルをレンダリングするには、次の手順に従います。

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

「Render Nodes」を選択する代わりに、「Render」を選択してレンダリングするノードを公開し、Drupal ノードとして API をすぐに公開することができます。 

ノードの公開

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

ノードを公開するには、次の手順に従います。

  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」をクリックします。

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

You create a new revision of a model by importing a new WADL file or OpenAPI Specification into an existing model, or by manually creating a new revision. After creating the new revision, you can render and publish the revision, which replaces the currently published Drupal nodes.

複数のリビジョンからノードを同時にレンダリングして公開できます。これは、モデルのリビジョンが 5 個存在している場合、任意のリビジョンまたは全リビジョンからノードを公開できることを意味しています。ただし、あるモデル内の API が別のモデルから公開されたノードと同じであり、この API を公開した場合、この操作によって、古いバージョンの API は非公開にされ、最も新しい公開済み API の内容に切り替えられます。  

モデルのリビジョンを表示するには、次の手順に従います。

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

ノードの編集

After you render a node, you can edit it by using the Drupal editor. For example, you can edit the HTTP verb and description of an API, or add a new query or header parameter to the API. You can edit nodes created from a WADL file or OpenAPI Specification, or nodes that created manually.

You can also edit the original WADL file or OpenAPI Specification. When you are done with editing, import the WADL file or OpenAPI Specification back into the model as a new revision, then render and publish your changes as described above. 

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 があり、モデルのインポート後、SmartDocs が、インポートされたモデルの POST API と既存の POST API の間で一致を見つけたと仮定します。この場合、POST API を更新すると、Drupal ノード 91 も更新されます。SmartDocs が一致を見つけていない場合、新しい ID で新しい Drupal ノードが作成されます。

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

  • internalName: 内部モデル名
  • httpMethod: GET、PUT、POST、DELETE など、API の HTTP メソッド
  • 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 によって、コンテンツの多くは、{{body}}のような埋め込み handlebars 式を使用して、変数で駆動されます。既存の Handlebar 式のリストは、ファイル先頭のコメントで指定されます。Handlebars を使用したテンプレートのカスタマイズについては、http://handlebarsjs.com を参照してください。

Apigee では、SmartDocs テンプレートに行ったカスタマイズへのサポートを保証できません。コンテンツをライブポータルに公開する前に、カスタマイズ内容を必ずローカルでテストしてください。

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

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

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

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

既存のモデルに新しい API をインポートするとき、カスタム SmartDocs テンプレートがモデル内のすべての API に適用されます。

カスタム 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 をインポートしたりするときに使用されます。

既存のモデルに新しい API をインポートするとき、デフォルト SmartDocs テンプレートがモデル内のすべての API に適用されます。

デフォルト SmartDocs テンプレートファイルを復元するには、次の手順に従います。

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

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

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

個々のモデル用のテンプレートを変更するには、次の手順に従います。

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

SmartDocs 認証タイプの構成

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

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

  • 基本認証: ユーザー名とパスワードのペアとして基本的な認証資格情報を渡します。資格情報のタイプとして「Oauth」の使用を指定していない場合、API はデフォルトで基本認証を使用します。
  • 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 によって次のボタンが追加されるため、ユーザーは基本認証の資格情報を指定できます。

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

カスタムトークンの場合、SmartDocs は次を追加します。

基本認証の構成

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

WADL ファイル以外のソースから作成されたメソッドに対して基本認証を適用するには、次の手順に従います。

  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 でデフォルトの基本認証ではなく、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. 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 のモデルとテンプレートについて」を参照してください。

 

     

     

    Help or comments?