Tesla のデータをAPI経由で定期的に Google BigQueryに連携し分析できるようにする:CDataSync
Tesla API が触りたいけれど、車が高くて買えないので、Tesla API の Mock API Server を作って、擬似的に Tesla を所有している感覚を API で体験する
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を試せる状態が整います。