この記事について
僕は、go-swagger を使ったことはありませんが、 swagger （OpenAPI）とその周辺ツール（code generator）は死ぬほど使ってきました。
swagger を使うメリットや注意点についてはわかっているつもりです。
先日、「go-swagger ってどうなの？」と聞かれたので、その時思ったことを書きます。
go-swagger について
go-swagger は、swagger のAPI仕様定義を読み込ませると、サーバーサイドのコードを生成してくれるツールです。（リクエストのパースとかがいい感じにできるみたいです）
実際に使うとどんな感じ？、ってのは下記ブログが参考になりました。
swagger 周辺ツールを使う際の注意点
go-swagger に限らず、swagger 周辺ツールを使う場合の注意点を書きます。僕の経験に基づいた注意点です。
以下のリスクを検討し、メリットが大きければ go-swagger を採用するのが良いでしょう。
最新の Swagger Specification に対応しているかどうか
Swagger Specification は随時バージョンアップしていますが、
「go-swagger が Swagger Specification v3 に対応してないので、Swagger Specification のバージョンをあげられない」
という状態になると非常に困ります。
僕も過去にありました。dredd *1が Swagger Specification v3 になかなか対応してくれず、ずっと Swagger Specification v2 を使っていました。あまりにも対応が遅いので dredd を切り捨てて Swagger v3 にしました。
Swagger への追従が早い（そのツールの開発が活発かどうか）は最重要です。
生成される成果物の質に関するリスク
go-swagger は、Swagger の定義からサーバーサイドのコードを生成できますが、生成されたコードがバグだらけだと、非常に困ります。
go-swagger 以外の例も考えてみましょう。
例えば、逆に、APIサーバーのコードから Swagger の定義が生成できるツールがあるとします。そして、これにより作られた Swagger の定義から、JavaScript や Swift の API クライアントのコードを生成するツールを使うとします。
この時
- APIサーバーのコード → Swagger定義
- Swagger定義 → APIクライアントのコード
この両者の変換の品質が相当高くないと、APIクライアントのコードが使い物になりません。2回変換をかます場合は、さらにツールの品質にを使う必要があります。
自動生成により、仕様と実装の乖離がなくなり、作業も削減できるように思えますが、それはツールの完成度に依存しているのです。
ツールの品質は事前に分からないことも多いので、品質を測るだけでなく、このリスクに対してメリットが上回っているのか、考えるのが重要です。
Swagger 依存が高すぎないかどうか
Swagger は REST API を記述するものであるため、REST、つまりリソース指向になっていないAPIは記述出来なかったり、複雑になったりします。
Swagger で表現できないものは go-swagger で提供できない、となると困ることがあります。
あるいは、諸事情により、Swagger 定義は書かずにAPIだけ作る場合もあるかもしれません。
その際に、Swaggerの定義が無くても、最悪手でAPIを実装できる機能が用意されているとありがたいです。
まとめ
何も考えずに swagger 自動生成系のツールをいれるとヤバいメンテナンスコストがかかります。
我々も openapi-generator には苦しめられました。
メリットが目に付きやすいですが、デメリットも結構あるので、メリット・デメリットをしっかり見極めるのが重要です。
