Cloud Endpoints に API ドキュメントの自動作成機能を追加
Google Cloud Japan Team
Cloud Endpoints は Google Cloud Platform(GCP)上での API の開発、デプロイ、管理を支援するサービスです。これを使用すると、お客様は API のロジックや設計に集中でき、その他すべてのことは Google のチームが処理します。Google はこのほど、そうした「その他すべてのこと」を拡張し、開発者が API とのやり取りの方法を確認できる新しいデベロッパー ポータルを発表しました。
デベロッパー ポータルは、お客様の API を利用したい開発者が最初にチェックする場所です。どうすれば API を評価できるか、どうすれば API を呼び出すコードを機能させられるかといった彼らの疑問に答える場になっています。また、API の拡張や変更に合わせてドキュメントを更新する方法を知りたいなど、API を開発するお客様の質問にもお答えします。
お客様としては、監査、レート リミットの設定、モニタリングなどと同じように、ドキュメントよりも API の開発に集中したいところでしょう。お客様のブランド戦略やコンテンツに合わせてカスタマイズされたデベロッパー ポータルを簡単に立ち上げられ、その内容を最新に保つための手間を最小限に抑えることが求められているはずです。
たとえば、Swagger Petstore(YAML)のデベロッパー ポータルは次のとおりです。


ポータルには、左から順に、メソッドとリソースのリスト、API 開発者が追加したカスタム ページ、個々の API メソッドの詳細情報、API を直接試せるインタラクティブなツールが含まれています。
gcloud を使ってプッシュした仕様はデベロッパー ポータルにもプッシュされるため、ポータルは常に最新状態に保たれます。デベロッパー ポータルでは、ドキュメントを読んだり、ドキュメントを見ながら API を対話的に試したりできるほか、チームでポータルをシェアすることも可能です。また、ポータルにカスタム ドメインを参照させるように設定し、チュートリアルやガイドといった独自ページを追加することもできます。その場合は、カスタム ドメインのために Google が SSL 証明書をプロビジョニングします。
さらに特筆すべきは、このポータルが最初から gRPC と OpenAPI の両方に対応していることでしょう。そのため、どちらの API を使っていても、ドキュメントはいつも最新の状態に保たれます。
Cloud Endpoints デベロッパー ポータルのアルファ テストに参加されたお客様からは、たくさんのフィードバックをいただきました。そうしたご意見は、今後数か月以内に追加される新機能に優先順位を付けるうえで大変参考になります。
* この投稿は米国時間 3 月 28 日、Software Engineer の Andrew Gunsch と、Product Manager の Israel Shalom によって投稿されたもの(投稿はこちら)の抄訳です。
- By Andrew Gunsch, Software Engineer, and Israel Shalom, Product Manager