CData API Serverで作成したAPIのドキュメントをSwaggerHubで共有する
はじめに
データアナリティクス事業本部のkobayashiです。
CData API Server を使うことで多種多様なデータソースに対しREST APIを簡単に構築できるようになるのですが、ドキュメントの作成も同時に行われます。作成されるドキュメントはOpen API Specification（以下OAS）ドキュメントなのですがこれを外部サービスのSwaggerHubで管理し公開することで開発者向けにAPIドキュメント表示やクライアントのライブラリの生成が行えます。
今回はこのCData API Serverで作成したOASドキュメントとSwaggerHubの連携方法をまとめます。
CData API Serverのインストール方法やデータソースの設定方法は下記のエントリをご参照ください。
環境
- Windows 10
- CData API Server - 19.0.7362.0
CData API ServerでのAPI確認
CData API Server上のAPIドキュメント
データソースと接続しデータソースのテーブルを元にリソースを作成するとAPI自体は簡単に作成できます。これを確認するには、ページトップのメニューからAPIを押下してREST APIページへ進むことで確認できます。
ここには、ディスカバリー項目として各種エンドポイント、リソース項目としてREST APIリソースが確認できます。
この画面でも十分APIドキュメントとしての役割は果たしているのですが、SwaggerHubに連携することで「ドキュメントがよりリッチになる」、「ドキュメント上からテストが行える」、「ライブラリの生成が行える」ためSwaggerHubに連携したいと思います。
OASドキュメントのエンドポイント
ディスカバリー項目の中にある/api.rsc/$oasがOASドキュメントのエンドポイントになります。この中身をSwaggerHubに連携することで開発者向けにAPIドキュメント表示やクライアントのライブラリが生成が行なえます。
表示の例ですとhttp://192.168.7.129:8153/api.rsc/$oas がそれに当たります。
SwaggerHubでAPI作成
APIのインポート
SwaggerHubで行うことはCData API Serverで作成されたOASドキュメントを読み込むだけです。読み込む方法は2種類あり、
- json or yaml ファイルを読み込む
- OASドキュメントのエンドポイントを指定する
です。今回のCData API Serverはローカルで起動しており、外部からはアクセスできない状態なので「jsonファイルを読み込む」で連携します。
1.http://192.168.7.129:8153/api.rsc/$oas にアクセスし、内容をjsonファイルに保存する。
2.SwaggerHubにサインインした後に左のメニューからCreat New > Import and Document APIを押下する。
3.Import APIのモーダルが立ち上がるのでPath or URLに1で作成したjsonファイルを指定し、UPLOAD FILEでファイルをアップロードする。
APIの確認
APIのインポートが終わると下記のような画面に遷移します。
この画面の右上のExportを押下すると多くのプログラミング言語のクライアントのライブラリが生成できます。
ドキュメントの画面はAPI・メソッドごとにわかりやすい形で表示されています。またアクセストークンの設定をしておけばこの画面から実際にAPIを叩いてレスポンスを確認することもできます。
まとめ
CData API ServerとSwaggerHubを連携してドキュメントを作成してみました。 次回はCData API Serverのより詳細な使い方をまとめたいと思います。
最後まで読んで頂いてありがとうございました。
