SmartDocs の更新

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

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

要件

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

SmartDocs API リファレンス ドキュメントについて

以下の説明に従って API 管理を追加します。

API 用の OpenAPI ドキュメントが Endpoints Frameworks によって作成されます。OpenAPI ドキュメントを Endpoints サービスにデプロイするたびに、SmartDocs によってポータルの API リファレンス ドキュメントが生成されます。SmartDocs UI は、Angular Material という最先端の UI コンポーネント ライブラリに基づいています。デベロッパーは SmartDocs API リファレンス ドキュメントを確認し、その API ドキュメントを表示したまま [この API を試す] ウィジェットを使って API を操作できます。

SmartDocs を生成するために使用される項目について

以下の説明に従って API 管理を追加します。

Endpoints Frameworks により、API 用の OpenAPI ドキュメントが JSON 形式で作成されます。OpenAPI ドキュメントを(gcloud endpoints services deploy を使用して)デプロイすると、Endpoints Frameworks が作成した OpenAPI ドキュメントに基づき、SmartDocs によってポータル向けに更新された API リファレンス ドキュメントが生成されます。

Endpoints Frameworks は、API 用に作成する OpenAPI ドキュメントに説明を組み込みません。API のユーザーにポータルの URL を提供する前に、OpenAPI ドキュメントの API、メソッド、パラメータに説明を追加することをおすすめします。

OpenAPI を初めて使用する場合は、Swagger basic structure ウェブサイトをご覧ください。このサイトには、サンプル OpenAPI ドキュメントが用意されており、ファイルの各セクションの簡単な説明があります。詳しくは、OpenAPI の仕様をご覧ください。

メタデータのセクションで説明されているように、description フィールドの値には複数の行を含められます。また、このフィールドは GitHub Flavored Markdown をサポートしています。

ユーザーが API のメソッドの使用方法を理解しやすくなるように、パラメータ セクションリクエスト本文description フィールドを追加することをおすすめします。

OpenAPI ドキュメントには、次のような内容が含まれています。

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

これらのフィールドの値は、ポータルでは次のように表示されます。

  • title: ポータル ホームページでは、title の値が、プロジェクト内の API を一覧表示するセクション、API のホームページ(値の末尾に「documentation」という語が付加された形)、API のタイトルバーに表示されます。

  • host: ポータル ホームページでは、host の値(Endpoints サービス名でもあります)が、プロジェクト内の API を一覧表示するセクション、[設定] ページの [API] タブに示されるプルダウン リスト内に表示されます。

  • version: メジャー バージョン番号は、API ポータルの URL で使用されます。

title フィールドの値を変更し、API の description フィールドを追加できます。たとえば、次のようにします。

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

SmartDocs を再生成する

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

  1. Endpoints Frameworks で生成した openapi.json ファイルを変更します。

  2. openapi.json を再デプロイします。

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

  4. 後で openapi.json ファイルの再生成が必要になった場合に、変更した openapi.json ファイルを、上書きされない場所に保存します。API に変更を加えて openapi.json ファイルを再生成する場合は、新しく再生成された openapi.json 内の変更と前に行った変更をマージする必要があります。

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