本記事はAsiaQuest Advent Calendarの1日目です。
はじめに
こんにちは、DE部GE課の松浦です。今回はOpenAPIの移行についての話です。
OpenAPIの仕様に則ってAPI仕様書を書くことはあると思いますが、バージョンアップ等の話はなかなか見つからず判断条件等に困ったため、記事にしてみました。OpenAPIの概要と歴史的背景、今はどのバージョンが安定しているのかについて、バージョンの移行経験を踏まえてまとめています。
ちなみに、OpenAPIは基本セマンティックバージョニングを利用されていますが、本記事ではOpenAPIのバージョンのみの表記するときに、便宜上「v1.0.x」のようなバージョンを表す「v」およびワイルドカードとなる「x」を基本的に利用します。
OpenAPIとは
WebAPIをJSON/YAMLで記述、定義するためのオープンな仕様のことです。Apache ライセンス 2.0 で公開されています。OpenAPIを利用することで、定義したJSON/YAMLファイルからテスト用のスタブやAPIドキュメント、コード生成やバリデーション定義まで生成できたりします。
SwaggerとOpenAPIの歴史的背景
ググってみると、SwaggerとOpenAPIが混同していてよく分からなくなると思います。
OpenAPIはもともと、Wordnik社が開発していたWebAPIをJSON/YAML形式で表現できる仕様およびツール群を指す「Swagger」というスイートツールの一部でした。2011月の9月にオープンソース化され、2015年に Wordnik社の親会社である Reverb Technologies社から SmartBear社がSwaggerを取得し、2015年11月に Linux Foundation と協力して OpenAPI Initiative（OAI）という組織を新たに設立しました。その後、当時の最新版であるSwagger2の仕様を OpenAPI Initiative に渡した結果、OpenAPI2.0 が誕生した経緯となります。
なので、Swagger2とOpenAPI2.0は同じものと考えて問題ないです。SwaggerのJSON/YAML定義部分はOpenAPIとして独立しましたが、スイートツールとしてSwaggerUIやSwaggerEditorはSwaggerとして残っています。
要約すると、元々はSwaggerとして提供されていたけど、今オープンソース化されてOpenAPIという名前に変わったということです。
OpenAPI3.x.xに移行するに至った背景
開発しているシステムでは Google CloudのAPI Gatewayを利用する予定でした。
API GatewayではOpenAPI2.0にしか対応していないため、開発当初ではOpenAPI2.0でYAMLを書いていました。
しかし、途中でAPIGatewayを利用しない方針になることが決定して、バージョンを再検討することになりました。
OpenAPI3.x.xではv2.0と比べて色々と変更点がありますが、自分のチームの場合は各環境リストを定義できるserversがv2.0にないことが問題の1つとして上がっていました。定義したWebAPIをドキュメント化する際に、各環境のサーバー一覧を表示させたかったのですが、v2.0の仕様に従う形では表現できません。
無理やりv2.0にserversの項目を定義すればドキュメント化は行えましたが、あまり望ましくない形だったので、v3.x.xに移行したいという思いがありました。
他にも後述するOpenAPI3.x.xに移行するメリットが大きいとの結論になり、移行しました。
注意点として、OpenAPI2.0は 2014年に定義されているのでかなり古い仕様となります。
上記の理由のような制限された環境でない場合は最初から OpenAPI3.0.0 以降の仕様を採用するのが良いと思います。
また Google Cloudについても補足しておくと、上位互換であるGoogle Cloud ApigeeではOpenAPI3.0.0を利用できるので、
もしGoogle Cloud環境でAPI Gatewayを利用予定の方はApigeeを検討しても良さそうです（ちょっと高い）。
v3.x.x内のどのバージョンに移行するか
現在OpenAPIの3.x.xはv3.0.xとv3.1.xに大きく分かれますが、以下の理由から最終的にOpenAPI3.0.3へ移行する形となりました。
v3.0.xは対応しているツールが現状一番多い
OpenAPI.Toolsによると、v2.0 / v3.0.x / v3.1.x を比較したとき、一番幅広くツールに対応しているのがv3.0となります。
v2.0 → v3.x.xへの移行を考えると、Convertツールが多いv3.0.xで良さそうです。
実際今回の以降ではv3.0.xまで対応しているツールを利用して移行しました。
v3.0.xとv3.1.xには破壊的変更が含まれている
OpenAPI3.0.xからはセマンティックバージョニングが採用されています。
セマンティックバージョニングでは、マイナーおよびパッチのバージョンアップでは破壊的変更をしないルールがありますが、v3.0.xとv3.1.xの間には破壊的変更が含まれています。
v3.1.xでは、JSONスキーマの100％互換性対応が含まれているため、破壊的変更が発生したようです。
OAI内でもv3.1.0にするかv4.0.0にするかは議論されたようですが、最終的にセマンティックバージョニングのルールを今回だけ破ることにしたようです。
OAI / v3.1にするかv4.0にするかの話に詳細が記入されているので、気になる方はこちらをご確認ください。
Stoplight社からも、内容をまとめた記事がWhat's the Difference Between OpenAPI Types 2.0, 3.0, and 3.1?として出されているので、こちらも参考になりました。
v3.0.3へ移行する
移行方法はいくつかありますが、npmで管理されておりCLI経由で簡単にコンバートできる swagger2openapi を採用しました。
Swagger Editor にもコンバート機能があるため検討しましたが、コンバート時にSmartBear社の会社へデータを送信して変換していたため、今回は利用を断念しました。
Swagger Editor はもともと仕様を決めていたSmartBear社が開発しているツールなので、データ送信が許容できる場合はこちらを利用するのが良いと思います。
swagger2openapiを使う
まずnpm経由でswagger2openapiをインストールします。
npm install -g swagger2openapi
次に対象のYAMLファイルを変換します。
swagger2openapi --yaml target_file.yaml > output_file.yaml
これだけで、v2.0からv3.0.0への移行ができます。
表題の通りv3.0.3への移行としたかったので、変換後は自分で確認して一部書き直しました。
まとめ
今回OpenAPI周りの歴史的背景を調査して、SwaggerとOpenAPIの関係性が理解できてよかったです。
OpenAPI周りは日本語記事だと古い内容だったり、バージョンが違っていたりするので、記事を読むときにはバージョンに注意する必要があります。
もしOpenAPIの仕様や項目が不明な場合は、面倒くさがらずにSmartBear社が公開している「OpenAPI Specification」かOpenAPI Initiativeが出している「OpenAPI Specification」のページを見て確認するのが一番の近道です。
参考資料
- 歴史的背景の調査
- Google Cloud 仕様
- v2.0からv3.x.xで変わったこと
- v3.0.xからv3.1.xで変わったこと
- v3.0OpenAPI仕様
