JSON から OpenAPI（Swagger） Spec のモデルを生成するのに「Swagger toolbox」が便利
OpenAPI（Swagger）Spec を書いていて、真っ先に面倒かつ苦痛なのが Model 部分の定義だと思います。
予め OpenAPI Spec を生成するように Web API側を定義していたりすれば、話は別ですが API Design First で構成していく場合、大量の定義をYAMLで書いていかないといけません。 また、すでに存在しているWeb APIからOpen API Specを書き起こす、みたいなプロジェクトの場合も同様ですね。
そんな苦痛な Model 生成が「Swagger toolbox」というWebアプリで一層（半分くらい）できるのでオススメです。
swagger-toolbox.firebaseapp.com
使い方は簡単です。左側に Model を生成したいJSONを貼り付けて「Convert」をクリックするだけ。
OpenAPI Spec の Model 作成に Swagger toolboxがとてもイケてる。 pic.twitter.com/R9yaNAQFsN
— Kazuya Sugimoto @CData Software Japan (@sugimomoto) 2020年1月18日
もし、Example を含めたい場合は「Include the example to the output」にチェックを入れればOK。
素晴らしい。
OpenAPI（Swagger） Spec のバージョンを 3.0 から 2.0 に変換したい：API MATIC を試してみた
2.0 から 3.0 に上げたいならまだしも、3.0 から 2.0 に下げたい？ 何をバカなことを言っているのだ？ と思われるかもしれないんですがちゃんとした理由がありまして
PowerApps のカスタムコネクタが OpenAPI Spec から生成できるんですが、現在 2.0 しかサポートしていないんですね。
でも、私が個人的に作っていた API が OpenAPI Spec 3.0 なのですね。（わかってたのにー (ﾉｼ 'ω')ﾉｼ ﾊﾞﾝﾊﾞﾝ）
なので、変換できるツール無いかなーと探していたら、ありました！
API MATIC
「API MATIC」という API定義から各言語のSDKを生成するサービスがあるんですが
その機能の中に「API Transformer」というものがありまして、OpenAPI以外にも、各種API Specを相互変換！
しかも、Postman Collection までサポート・・・！！！！！
素晴らしい！！！
なお、基本的には Web API を提供している側向けのサービスなので、お値段は月々 $9.9 ～。
今回はとりあえず Trial で試してみました。
使い方
使い方は簡単です。サインアップしたら、ダッシュボードの画面右上に「Transform API」というボタンがあるので、これをクリック。
あとは対象となる YAML を選んで、Export Format から OpenAPI/Swagger v2.0 を選べばOK！
ValidationがOKだったら、Proceed をクリックすると、OpenAPI/Swagger v2.0 の Spec がダウンロードされてきます。
やったね！
Postman Documentation / API Network が便利だよ！
この記事は「Postman Documentation / API Network が便利だよ！ 」ということを言いたいだけの記事です。
Postman Documentation / API Network とは？
Postman には Webベースのドキュメントを公開する機能があります。
作成すると以下のような見やすい API リファレンス と APIテスティング が行えるWebSiteが自動的に作成されます。
もちろん、Postmanコレクションも取得して、ローカルのPostmanで実行することも可能です。
ちなみに、私の観測範囲で、このPostman Documentation を使ってAPI ドキュメントを公開している日本のクラウドサービスは「Bカート」さんくらい。
ちなみに、Postman では生成したドキュメントをPostmanの サイト上で公開・共有できる仕組みを提供しています。
それが Postman API Network です。
現在、470種類ほどのAPIが公開されており、APIドキュメントの参照、Postman Collectionの入手が可能になっています。
APIを検証する時、Postmanコレクションを毎回手作業でがつがつ作るんですが、予めこういうサイトで公開されていると、すごく楽で助かります。
最後に
パブリックなAPIは、みんな Postman API Network で API documentを公開してくれればいいのに！！！
Postman Collectionは OpenAPI SpecやRAMLからも取り込めるので、敷居は低いと思うんですが。
PowerApps / PowerAutomate カスタムコネクタを Postman コレクションから作成する
OpenAPI（Swagger）Spec から Postman Collection を生成すると楽にAPIテストができる
Postman で API を実行するのは結構手軽にできるんですが、エンドポイントが多かったり、URLパラメータやヘッダーを逐次、ドキュメントから持ってくるのは結構面倒です。
もし、そのAPIがOpenAPI（Swagger） Specを公開していたら、それを取り込むと簡単にPostmanコレクションを生成できます。
OpenAPI Spec って何？
ここを参照しましょう。
OpenAPI Specification（OAS）は、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピュータの両方がサービスの機能を発見して理解することを可能にする、 プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を定義します。
対象のAPI
今回対象にするAPIは私が以前作成して、パブリックに公開している O'Reilly Book List API です。作り方はこちら を参照してください。
- URL：https://decodeapiserverdemo.azurewebsites.net/api.rst
- ID：user（ReadOnly）
- Password：3s3E4a4r7Q7d2a1J0i4l
- AuthType：Basic
以下のURLからOpenAPI Specをダウンロードできます。
http://decodeapiserverdemo.azurewebsites.net/api.rsc/$oas
取り込み方
取り込み方は簡単です。Postmanを立ち上げて、「Import」ボタンをクリックし
事前にダウンロードしておいた、OpenAPI（Swagger）Specのファイルをドラッグ・アンド・ドロップするだけです。
あとはTeamで共有するかどうかと、コレクションを作成するかどうかを決めて、Nextをクリックすれば完了です。
以下のようにコレクションが生成されて、
手軽にAPIを試せる状態が整います。
Reference
PowerApps / PowerAutomate カスタムコネクタを OpenAPI（Swagger）Specから作成する
最近、少し PowerApps / PowerAutomate のカスタムコネクタ周りについてまとめていました。
現在何種類かの作り方があるんですが、それぞれの特徴を捉えるために、何回かに分けて記事にして行こうと思います。
- PowerApps / PowerAutomate カスタムコネクタって何？
- 現在カスタムコネクタがサポートしている作り方
- OpenAPI（Swagger）って何？
- OpenAPI（Swagger）で公開されているサービス
- 対象のAPI
- 出来上がるもの
- OpenAPI（Swagger）Specのダウンロード
- カスタムコネクタの作成
- カスタムコネクタを使ってみる
- おわりに
自分のはてなブログの投稿状況データをPowerBIで可視化する：CData XML ODBC Driver
先日公開した以下の記事で書いたのですが、自分のはてなBlogでどんな投稿をしているかPowerBIで可視化してみました。
最終的にできあがったのは以下のようなレポートです。
この記事ではこのようなレポートを作成するためのデータ取得方法について解説していきます。
その前にちょっとAPIの解説
はてなBlogにはいくつか外部からはてなBlogにアクセスするためのAPIが提供されています。
- Atom https://help.hatenablog.com/entry/feed
- RSS https://help.hatenablog.com/entry/feed
- AtomPub http://developer.hatena.ne.jp/ja/documents/blog/apis/atom
- oEmbed API http://developer.hatena.ne.jp/ja/documents/blog/apis/oembed
最初２つのAtomやRSSはおそらく使ったことがある方も多いと思いますが、Blogの更新状況を取得するためのAPIプロトコルです。
AtomPubはAtomのように外部からBlog記事を参照できる機能はもちろんですが、記事の登録や更新にも対応しているのがポイントとなるAPIです。
最後のoEmbed APIはこちらの解説記事がわかりやすいかと思いますが、名前の通り外部コンテンツへの埋め込みおよびその記事の参照用に特化したプロトコルです。
今回APIとして必要な要件は、過去の全記事に関する情報が参照でき、かつカテゴリ情報も取得する必要がありました。
そして、実はその要件を満たしたAPIは「AtomPub」一択です。
前２つのAtomとRSSは参照用としては優れているのですが、最新の記事参照のみに特化しているため、ページネーション、つまり過去記事の参照ができません。
oEmdedは参照するためにどの記事を参照したいか、といったURLが必要となるため、言わずもがな。
AtomPubはページネーションをサポートし、カテゴリも取得できるので、今回のようなユースケースにはうってつけのAPIとなっていました。
実装方法
それでは実際に実現する方法なのですが、この記事でははてなBlogデータをAtomPub経由で取得するためのコネクタを使うので、特にプログラミングの要素は出てきません。
なので必要なものは、以下の「CData XML ODBC Driver」と
XML ODBC Driver - ODBC | ODBC Drivers | ODBC Connection | ODBC API
XML ODBC Driverを通じてはてなBlog AtomPubに接続できるようにするための設定ファイルだけです。
あとは分析用に Microsoft Power BIを使いました。Tableauなどでも同じ用に実施できると思います。
API Keyと接続URLの取得方法
それでは実際にデータの取得を行っていきたいと思いますが、AtomPub APIは接続するために「接続用URL」と「API Key」が必要となります。
はてなBlogの管理画面から「設定」→「詳細設定」に移動
AtomPubにルートエンドポイントとAPIキーの情報があるので、これを利用します。
設定ファイルをダウンロード
次に接続用の設定ファイルをダウンロードします。通常設定ファイルは「CData XML Driver」用で都度カスタマイズする必要があるのですが、今回は私が作成してしまっているので、以下のURLからダウンロードして利用できます。
上記URLから「HatenaBlogFeeds.rsd」というファイルをダウンロードし、任意のフォルダに配置（例：C:\CData_REST\Hatena）します。
CData XML ODBC Driverのインストールとセットアップ
続いて「CData XML ODBC Driver」をインストールします。有償の製品ですが、30日間のトライアルバージョンがあるので、今回はそれを利用します。
以下のURLから評価版をダウンロードし
http://www.cdata.com/jp/drivers/xml/odbc/
ダウンロードしたexeファイルを実行して、セットアップを行います。
セットアップ完了後、DSN構成画面が表示されるので、以下のように必要な情報を入力します。
- URI：管理画面から入手したAtomPub用URLの末尾にentryを付与したものを入力（例：https://blog.hatena.ne.jp/sugimomoto/kageura.hatenadiary.jp/atom/entry）
- Auth Scheme：Basic
- Password：管理画面から入手したAtomPub用API Keyを入力
- User：はてなBlogのログインユーザーIDを指定
- Location：設定ファイルのフォルダパスを指定（例：C:\CData_REST\Hatena）
以上で下準備は完了です。
PowerBI からはてなBlog AtomPub APIに接続
それではPowerBIに はてなBlogのデータをロードしてみましょう。
PowerBIを立ち上げて、「データを取得」をクリックし
「ODBC」接続を選択します。
先程設定したDSN名を選択して「OK」をクリックすると
以下のようにはてなBlogのデータがフラット化されて取得できるテーブルが選択できるようになっています。これを読み込みます。
以下のような感じでデータが取得されました。設定ファイルが自動的にAtomPubのページネーションもするようになっているので、過去の全記事を取得してくるようになっています。
あとはこのデータを使って、PowerBIの機能でビジュアライズするだけです。
その他：カテゴリの取り方
ちなみに、デフォルト状態のカテゴリ情報は以下のようにカンマ区切りになっているのですが、
これだとリレーショナルなデータになっていないので、うまく可視化できない部分が出てきますよね？
これを以下のようにBlogIDとリレーションされた形式にする方法もあります。
方法は簡単で、まず元になっているクエリを複製し、適当に「Category」といった名前に変更、IdとCategoryTerm以外の列を削除します。
次に「列の分割」から「区切り記号による分割」を選択し
「コンマ」の区切りごとで列を分割します。
以下のようなデータができあがるので、この項目を選択して、「列のピボット解除」を実行します。
すると以下のようにIDに各カテゴリがリレーションされた形のデータができあがります。「属性」列は最終的に消してしまっても大丈夫です。
