7月22日に行われたAPI Meetup Tokyo #15はOpenAPI Specification（旧Swagger）特集でした。イベントの告知後、あっという間に満席になってしまったというほど、注目が高まっているOpenAPI Specification、今回はそのレポートになります。
1. OpenAPI Specification/Swagger概要
API Meetup運営チーム/Apigee 関谷和愛さん
OAS（OpenAPI Specification）はREST API記述のフォーマットになります。IDLの一種で、APIを機械可読な形で記述して様々な自動処理につなぐことができます。ざっくりいうとWSDLのREST版です。
Swaggerは純粋に社内のツールとして作ったのがはじまりです。JSONだけじゃなくYAMLでも書けるようになったり、一つのファイルにまとめるといった機能が追加されていきました。Swagger 2.0がOAS 2.0に名前を変えたので、中身は同じものです。Swaggerというと、ツール群も含んだ名称になっていました。今後はOASといった場合は記述フォーマットを指します。
APIのエコシステムを作りやすい環境を作っていくのがOAI(OpenAPI Initiatize)になります。OASの目指すところはAPIライフサイクル全体をカバーするフレームワークであって、単なるドキュメント生成ツールではありません。例えば以下のような展開があります。
- 設計ツール
- ドキュメント
- テストケース
- モック
- バリデーション
- スケルトンコード
- SDK
OAS3.0は直接の互換性は保たれない模様です。GitHub上で議論、開発しているので仕様策定に参加することも可能です。リリースは秋頃を予定しています。TDC（Technical Developer Community）がリードしています。
2. OpenAPI Specification を使ったスマートな API 運用
株式会社 KUFU 芹澤雅人さん
仕様書は大事だけど軽視されがちです。今回はそのケーススタディになります。
黎明期のWeb API
2000年代初頭に実装されたAPIです。実装言語はJava、レスポンスはXML、仕様書はWordとなっています。
欠点として、そもそも仕様書が運用されていませんでした。記載の抜け洩れが目立ち、実装を確認した方が早いといった状況です。仕様書がしっかりしていないと開発はもちろんコミュニケーションコストが大きくなってしまいました。さらに設計思想の不統一が起きやすくなっており、仕組みを作らないと開発者は仕様書をメンテナンスしない実例となりました。
2011年頃
言語はJavaで、SphinxをI/F仕様書にしました。
良かった点として、Sphinxを採用したことです。Sphinxはrstで記述する仕組みです。ソースコードで同じリポジトリで管理していたので、レビュー対象となるので抜け洩れしづらくなっていました。文書はHTML/PDFに変換できました。
欠点として、仕様書の運用コストが少なからずありました。また、エンドポイントを追加する時などは結構なコピペ作業がったり、エンタープライズ向けに別で仕様書を生成できませんでした。エンタープライズ企業向けに綺麗な仕様書を作ると喜ばれ、心なしか問い合わせも友好的でした。
ここでの学びとしては、仕様書とソースコードは近ければ近いほど良いということです。また、HTML以外のフォーマットでとれるといいと思います。
最近のWeb API
最近はSmartHR APIで実践しています。言語はRubyを使っています。先にWeb APIを実装して、後からSwagger Specを生成するアプローチとなっています。デザインも良いですし、運用コストも気にならないレベルまできています。
3. Swaggerを使用したモデルファーストなAPI開発のよもやま話
TIS株式会社 小西啓介さん
スマホアプリ向けのAPI開発でAPI仕様をExcelで書きたくありませんでした。漏れのないフォーマットが作れませんし、APIスタブを生成したくてSwaggerにたどり着きました。
とは言え、最初はExcelなどで整理するところからはじめました。
- 業務機能の洗い出し
- リソース抽出
- 項目名の名寄せ、英字検討
Swaggerは項目名だけを書くようにしています。
- Path
- Operation
- 必須リクエストパラメータ
いきなり細かく書くのではなく、骨格が固まったら詳細記述するようにしています。
Swagger Editorについて
とても使いやすいわけではありません。構文エラーを取るのは一苦労です。他のツールで作成してから貼り付けると多数のエラーが出ます。気付きづらい機能として、Ctrl + Fを2回で置換が出ます。なお、Swagger UIとの互換性はありません。
Swagger UIについて
カスタマイズが必要です。例えば認証関係、バグパッチ対応、日本語化など。なお、表示されるレスポンスは加工されています。例えば、
- CORSのXHRでのエラーは不明
- 304は200で表示
などです。また、表示されないSwaggerの情報があります。そのためSwaggerファイルも公開すべきです。後、アルファベット順で必ずソートされるのが仕様となっています。
Swagger Nodeについて
フォーマットバリデーションが便利です。リクエストだけでなくレスポンスのバリデーションもしてくれます。なお、additionalProperties:falseにすると大変です。
Swagger仕様について
全体の構成が分かりづらいです。例えばリクエストとレスポンスが非対称で、リクエストは配列、レスポンスはマップで定義という違いがあります。
OpenAPI Specification Visual Documantationというサイトが便利そうでした。大事な部分はJSON Schema参照しましょう。両方見ないと分からないことがあります。
- hostパラメータは任意
- セキュリティ定義の（authorization uri/token uri）は絶対URLでhostとは無関係
- external doucmentを使えるが、表示されない
内部用、外部用に別に分けたいが一つのファイルの方が良いです。それを表示する際にフィルタリングするようにしましょう。
よく使うDefinitionの参照先は2つあります。
- Request Definition
- Response Definition
- Definition
descriptionの中にはGitHub Flavoredが使えるものと使えないものがあるので注意してください。
4. Lightning Talks by Open API Initiative members!
ここではLTとしてOpenAPI Initiatizeに参画している企業からその取り組みについて紹介がありました。
Mashape Augusto Mariettiさん
Mashapeは開発ツールを提供しています。API管理用ツールを提供しています。
- マーケットプレイス
- APIゲートウェイ（Kong）、オープンソース
- Gelato - Developer Portal
- キーの管理もできる
- アクセス管理
- Swaggerサポート
- Galileo
- API解析
- APIトラフィック
Paypal 岡村純一さん
PayPalはなぜ参加しているのか？それは二つあって、
- 対外的要因：より多くの人に使ってもらうため
- 対内的要因：製品を効率よく開発するため
PayPalのAPIが他のAPIと共通化されていれば使ってもらいやすくなるでしょう。内部APIも共通化されると内部でも開発しやすくなるんじゃないかと考えています。
PayPalは単なる決済APIからペイメントOSへと発展しています。社内の開発体制が大きくなっていくと、様々な言語で作られるようになります。一貫性を保つ、コミュニケーションコストの増大を防ぐのに共通フォーマットが必要になると考えています。
IBM 森住祐介さん
IBM API Connectについて紹介します。StrongLoopを買収したことでAPIの作成、実行、管理、保護までできるようになりました。
- どうやって迅速に開発するのか
- APIを実行するランタイムの品質と性能を確保するには？
- 管理を効率的に行うには？
- APIをセキュリティに運営するには？
クラウド、オンプレミスで柔軟に利用可能です。開発時、ローカルも使えます。
CLIでOAIに則った仕様書を作成できたり、GUIも提供されています。
Microsoft 佐藤直樹さん
Visual Studioプロジェクトテンプレートではアクセス制約、セキュリティを意識する場合はAPIゲートウェイが使えます。SwaggerからのAPIインポートがサポートされています。API AppsとLogic AppもSwaggerで連携できます。
SwashbuckleがSwagger API定義が生成します。Visual Studioにデフォルトで入っており、オープンソース・ソフトウェアです。API定義、CORS設定がLogic Appsとの連携を担います。Swaggerの直接読み込みやAPI Appsとの連携が行えます。
なお、Microsoftでは自社でも積極的に自社製品を使っています。Microsoft REST API Guidelineが最近リリースされました。ぜひご覧ください！
Apigee 関谷和愛さん
ApigeeはAPI管理サービスを提供しています。Swagger EditorはApigeeのコントリビューションですが、Swagger UIは別な会社です。この辺りが連携での齟齬につながっているのだと思います。
OASについては次のようなサービスでサポートしています。
- APIゲートウェイ / Apigee Proxy
- 利用者ポータル / Apigee Edge
- API開発環境 / Apigee API Studio
- テスト・監視 / Apigee Test
OpenAPI Specificationは今後のAPI開発において無視できない仕様となっていくでしょう。今回の勉強会では余すところなく、それらの情報がキャッチアップできていたと思われます。
