Apitore blog

Apitoreを運営していた元起業家のブログ

API Meetup Tokyo #15を聴講してきた

はじめに

API Meetup Tokyo #15を聴講してきました。今回はSwagger特集のガチガチテック系です。このMeetupはAPI界隈の最先端の情報(Oauth、microserviceなど)が知れる上に、実際に最前線で働く技術者の生の声が聞けるたいへん質の高い勉強会です。勉強会にはこの1年で様々なものに参加してきましたが、これはトップクラスです。 ※資料が公開されたら載せます。 image

OpenAPI Specification/Swagger概要

API Meetup運営チーム/Apigee 関谷和愛さん image ※仕事で遅刻したので聞けませんでした。。。

OpenAPI Specification を使ったスマートな API 運用

株式会社 KUFU 芹澤雅人さん WebAPIの設計開発運用販売をしている。 image SmartHRを展開 労務の手続きは相当たいへん。それをスマートに解決する。 手書きからWebへ。そのまま従業員DBとして活用出来るし、マイナンバーにも対応。採用ツールや社内システムとの連携はWebAPIで行っている。 WebAPIの課題 仕様書が軽視されがち、だけど利用者にとっては影響が大きい。仕様書がWordの時は、管理コストが高すぎた。仕様書がSPHINXになったとき、Wordよりはだいぶマシになったが、まだ大変だった。例えばWebAPIを社内外で分けるとしたら、それぞれ仕様書を書く必要があった。

Swaggerの場合も同じな気がするけど、私が知らないだけかな?

OpenAPI Specification (旧Swagger) ソースコードにアノテーションを記述していくと、自動的に仕様書を作れる(Swagger-UI)。モデルファーストで実装もできる(Swagger-CodeGEN、Swagger-Editor)。導入は簡単で、主要な言語はたいていSDKがある。実装に即して仕様書が書けるので、色々と便利。Swagger-UIではブラウザ上でレスポンスチェックできる。フォーマットは綺麗に整えられている。実際に使ってみたが、楽チン。ただし、公開する仕様書なので、Swagger-UIはだいぶカスタマイズした。

他の講演者も言っていたが、Swagger-UIは基本的にカスタマイズするそう。私の印象では、SwaggerはUIを標準化することでデベロッパーがWebAPIの内容を理解しやすくする意図があるように思っていたので、むしろカスタマイズはしないほうが良いのかと思っていた。実際、Swagger-UIはわかりづらい部分もあるが、慣れればとっつきやすいと思う。

Swaggerを使用したモデルファーストなAPI開発のよもやま話

TIS株式会社 小西啓介さん SIer 12年目。 image [slideshare id=64300306&doc=swaggerapi-160723034026] スマホアプリ向けのAPI開発で仕様書をExcelで書きたくなかった。 -> Swaggerを使おう! Redmine APIをSwaggerで作ってみた。Node.jsをバックエンド。データストアをApache Usergrid。 Swaggerは使いやすいが、、、

  • Swagger-Editorの入力補助はそこそこスマート(あくまでそこそこ)。
  • 構文エラーを取るのは一苦労。
  • 気がつきにくい機能(置換はCtrl+Fを2回押す、とか)アリ
  • Swagger-UIとの互換性はあまりよくない。
  • Swagger-UIのカスタマイズは必須。Oauthをパラメータで渡したいときとか、nameを変えたいときとか。
  • 表示されるレスポンスは加工されている。304エラーが200で返ってきたりするので、chromeの開発画面を適宜確認した方が良い。
  • 表示されないswaggerの情報がある。swaggerファイルを公開すべし。
  • アルファベット順にソートされてしまう。
  • Swagger Nodeは便利。Validationを助けてくれる。ぜんぶValidationするとちょっと大変。
  • Swaggerの仕様はわかりにくい部分もある。
  • 他にも色々(詳細は資料を参照!)

Lightning Talks by Open API Initiative members!

Mashape Augusto Mariettiさん

21歳でスタートアップ就職。HTTPレイヤーのマネージングをやる会社。4つのメインプロダクト。

Paypal 岡村純一さん

Paypalエヴァンジェリスト PaypalのRestAPIの仕様書はSwagger-UIをカスタマイズして使っているそう。社内向けのAPIはSwagger-UIそのものに近い形で展開。

IBM 森住祐介さん

スタートアップ支援を主担当。 IBM API Connectを展開。APIを管理するサービス。StrongLoopを買収した結果、作成や実行もサポートするようになった。APIを作ったらオンプレミスもクラウドも簡単にdeployできる。

Microsoft 佐藤直樹さん

Apigee 関谷和愛さん