猫でもわかるWebプログラミング

試行錯誤しながらエンジニア(プログラマー)として働く猫のブログ。技術的な話や、働き方の話、読書録とか、試行錯誤している日常の話。

go-swaggerで見る「swagger(OpenAPI)周辺ツールについて」

f:id:yoshiki_utakata:20200905221607p:plain

この記事について

僕は、go-swagger を使ったことはありませんが、 swagger (OpenAPI)とその周辺ツール(code generator)は死ぬほど使ってきました。

swagger を使うメリットや注意点についてはわかっているつもりです。

先日、「go-swagger ってどうなの?」と聞かれたので、その時思ったことを書きます。

go-swagger について

go-swagger は、swagger のAPI仕様定義を読み込ませると、サーバーサイドのコードを生成してくれるツールです。(リクエストのパースとかがいい感じにできるみたいです)

github.com

実際に使うとどんな感じ?、ってのは下記ブログが参考になりました。

future-architect.github.io

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 には苦しめられました。

github.com

メリットが目に付きやすいですが、デメリットも結構あるので、メリット・デメリットをしっかり見極めるのが重要です。