CData API Server で REST ful APIを作って、SwaggerHub でさくっと API ドキュメントを公開する

CData API Server では、さくっと REST Ful な Web API 開発ができるのですが、APIを生成するともれなくSwagger Spec のエンドポイントがついてきます。

そこで、ドキュメントの見やすさや Code Generate などのエコシステムが強力なSwagger（OpenAPI）を、CData API Server を使いながら、さくっとSwagger Hub で公開してみたいと思います。

SwaggerHub って？

SwaggerHub は OpenAPI（Swagger）による API 開発を行うための Spec Editor や Code Generator、Document 機能を備えたクラウドサービスです。

swagger.io

通常 オープンソースで提供されている一連の Swagger アプリケーションセットをサービス化したもの、言えばわかりやすいかもしれません。

そもそも Swagger って何？　という方はこちらのドキュメントがわかりやすいと思います。

news.mynavi.jp

news.mynavi.jp

CData API Server の構成

CData API Server は以下のURLからトライアルの取得が可能です。

今回はAzure Web Apps上に構成して、Swagger Hubと連携できるようにしてみました。データベースは適当なサンプルDBを使って、エンドポイントを構成しています。

Azure Web Appsへのデプロイ方法は以下の記事をどうぞ。

http://kageura.hatenadiary.jp/entry/2017/11/27/Azure_SQL_Database%E3%82%92CData_API_Server%E3%81%A7Web_API%EF%BC%88OData%EF%BC%89%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%8D%E3%82%8B%E3%82%88%E3%81%86%E3%81%AB%E6%A7%8B%E6%88%90%E3%81%97

CData API Server から Swagger Specの確認

それでは、まず構成したCData API Server から Swagger Spec を取得できるエンドポイントを確認したいと思います。

API Server の API ドキュメント画面に移動すると「/api.rsc/$swagger」というエンドポイントがあります。

このURLにをクリックすることで

以下のような Swagger Spec を取得できます。Swagger Spec は CData API Server のリソースを作成した時点で自動的に生成されます。

SwaggerHub

それでは、CData API Server の Swagger エンドポイントを使ってSwaggerHub でAPIを公開します。

SwaggerHub のプランは Free のもので大丈夫です。

SwaggerHub に移動して、左ナビゲーションから「Import and Document API」をクリック

Path or URL にCData API Server のSwagger エンドポイント URLを入力します。

おそらくログインが求められるので、CData API Server の API アクセス用ユーザーのIDとトークンを入力します。

以下の画面から入手可能です。

すると、以下のような画面に移るので、任意の名称とVersionを入力して「IMPORT OPENAPI」をクリック

以下のようにもともとJSON だったSwagger エンドポイントのデータもYAML形式に整形されて、SwaggerHubで公開されます！

もちろん、ここからClient SDKを Code Generate して使えるので、各種言語での実装が楽になりますね！