Swagger定義の管理場所について、
- コード上に定義する方法
- 定義ファイルを直接管理する方法
- API管理サービスを利用する方法
と、それぞれまとめました。
1. コード上にコメントとして記述する
JavaDocのように、コード上のコメントとしてannotationで記述していく方法です。Swaggerを利用するにあたり、真っ先に思い浮かべるお馴染みの記述方法ではありますが、やはり一長一短があります。
長所
- コード自体がリポジトリ管理されることで、APIの記述を別に管理する必要が無い。 *開発時にAPIのドキュメントの整合性が保たれやすい
短所
- 運用時においてはメンテナンスが行いにくい。
- 新規開発時なら導入はスムーズだが、すでに外部記述となっていた場合には相応のコストが掛かる。
- annotationのコード補完が、エディタに備わっていない。
- コード自体が長くなり、見通しの面ではデメリットになる。
メリットは傍受し、デメリットは工夫してカバーしていきましょう。
2. 定義ファイルとして記述する
Swaggerの定義ファイルそのままを、ファイルで管理する方法です。一見、JSONをそのまま扱うので、デメリットしかないように感じますが、定義ファイルを分割することで、冗長的な記述を抑えるメリットがあります。
もちろん、定義ファイルを一意性を考えずにそのまま記述してしまうと、同じデメリットが発生します。これは、小規模のAPIであれば、問題は有りませんが、大規模APIとなると修正コストが問題になるでしょう。
分割したSwagger定義ファイルが増えると見通しの面では不利になりますが、メンテナンス面では改修を行うに当たって精神的にも楽になるでしょう。
実際にSwagger定義ファイルを分割して管理するツールは、執筆の現時点（2016-08-31）で存在していないと思いますが、いわゆるJSON定義を分割する方法ですので、以下のようなツールを利用してJSONを置き換える事が可能です。
Swagger定義ファイルの分割については、また別の機会に紹介したいと思います。
3. APIサービスを使って記述する
各API管理サービスについても、Swagger記法が主流となりつつあります。既にAPIの管理サービスを選択するにあたり、Swagger記法があるかないかが導入の判断に関わることもあるでしょう。ここでは、Swagger定義ファイルがインポート＆エクスポートできるツールを紹介します。
Swagger Editor
Swagger定義を管理できる、WEBサービスです。
ツール自体は公開されています。プロジェクトで運用するのも選択の一つです。
licenseは、『Apache License, Version 2.0』となっています。
swagger-api/swagger-editor: Swagger Editor
AWSの『API Gateway』
AWSの API Gatewayを利用しているのであれば、Swaggerのドキュメントを出力できます。 また、API GatewayにはImport機能も備わっており、 どちらもASW用に拡張機能の記述もできるようなので、AWSだけで記述を完結するようにした方が良さそうです。
今後のSwagger定義ファイルの管理
別の記述方法としてAPIBlueprintがあります。記述はAPIBlueprintで出力はSwaggerのJSONファイルで対応するという選択肢も出てくるかも知れません。
Swagger APIによる記述においては、様々な場所で開発できるのも強みであったりしますが、「開発とAPI定義がもっと便利にシームレスにできないか？」と思うところがあります。Swaggerの定義ファイルを管理するのは、API開発において避けては通れなくなってきています。今後もSwagger管理についてはウォッチしていく必要がありそうです。
