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 で使用する JSON 形式の OpenAPI ドキュメントが作成されます。作成された OpenAPI ドキュメントをデプロイすると(gcloud endpoints services deploy を使用して)、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 リファレンスの gcloud endpoints services deploy をご覧ください。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

App Engine 用 Cloud Endpoints Frameworks
ご不明な点がありましたら、Google のサポートページをご覧ください。