SwaggerHubでのSwaggerチーム開発考察

まずSwaggerとは

RESTful APIを定義するためのフレームワークです。
このSwagger仕様に準じたドキュメントをSwagger Specと呼びます。
Swagger Specを表示するためのツールがSwagger UIで、作成・編集するツールとしてSwagger Editer、モックの作成ツールとしてSwagger Codegenといったツールが用意されており、これらを総称してSwaggerと呼びます。

この考察の背景

弊社では今システム刷新に伴い、API仕様書の作成を始めるところです。
そこで、APIドキュメントツールは何を使おうかとなったときにswaggerが挙がったのですが、Swagger Specはファイル分割が難しい点（できるにはできるが、Editor上で展開されない）、オンラインエディタではローカルファイルを直接編集できない点（ファイルをアップロードする必要がある）から「チーム開発には向いてなさそう」ということで悩んだときに、このSwaggerHubなるものがその悩みを解消してくれそうということで、調べた備忘録として残します。
主な内容は以下ページの「Collaboration & Sharing」にある、「Access Control and Secure Sharing」、「Issue Tracking and Commenting」、「Change Notifications」について、「実態はどのようなものなのかを調べた結果とその所感」です。
https://app.swaggerhub.com/help/index

Swaggerでチーム開発をするためにSwaggerHubを導入しようか悩んでいるという方の参考になればと思います。
14日間の無料トライアルがあるのでぜひ実際に試してみてください。

Access Control and Secure Sharing

作成したドキュメントのシェアについてです。SwaggerHubでは各APIごとにGitHubのように公開範囲・ロールが設定できます。
public/privateのAPIドキュメントが作成可能で、それぞれでシェアの仕方が異なります。

publicAPIの場合

すべてのSwaggerHub上のユーザーが参照出来る状態にあります。シェアしたい場合はリンクをコピーして送るだけです。SwaggerHubアカウントがなくても参照可能です。

privateAPIの場合

APIのowner、editorが参照できる状態にあります。普段はprivateだけど、例えば委託先や提携先へシェアしたい場合はCollaborateに追加後、view専用のroleを与えることでシェアができます。こちらはpublicとは異なり、SwaggerHubアカウントが必要です（organizationに所属していなくても閲覧可）。

Issue Tracking and Commenting

GitHubの要領で、任意の行にコメントが追加できます。コメントしたい行の＋ボタンを押すとモーダルが表示されます。

返信ももちろんできます。その他詳細機能は端折りますが、ブラウザリロードかけなくてもリアルタイムでコメント表示してくれる点はちょっといいなと思いました(返信はなぜかリアルタイムじゃないっぽい)。

Change Notifications

変更通知・・・。ここが個人的に一番気になっていたところでした。
SwaggerHubにおいては複数人同時に同じページのエディタを開くことが可能です。
そこで気になるのが複数人で平行に作業し保存した時にどうなるのか。
文字通り、「変更された通知が画面上部にポップアップで注意書きとして出てくる」だけでした・・・。

この通知はSAVEボタンを押したタイミングで他にエディタを開いている人へ通知されます（※通知されるだけ。ビューは更新されない）。
この通知が来ている状態でSAVEを押すと、以下の確認ポップアップこそ出ますが
今自分のブラウザに表示されている内容で全上書きされます（マージしてくれない）。

編集内容が違うラインだったとしても完全に後勝ちです。
同一行を別の編集者が更新していたとしても、後勝ちで、自分の更新が残ります。
どうしてもマージしたいとなると、通知が来たらVersionを新しく作成してそちらに保存した後、
①左上のAPI名クリック
②Compare & Merge APIボタンクリック
③Compare with API in SwaggerHubボタンをクリック
④API、Versionを指定しNEXTをクリック


すると、diffが見れるエディタが展開されるのでそこで編集して保存するといった方法で可能です。無理やり考えた方法なのでベストプラクティスがあるのかもしれません。

いいところ

1. ドキュメントの公開範囲を設定できる
2. 個々のユーザに対して適切なロールを付与できる
3. コメント機能があるためSwaggerHub上でレビューができる
4. diffツールがある

よくないところ

1. 自動でマージしてくれないため、複数人での編集作業がやりづらい
2. privateAPIを他者にシェアしたい時は、シェアされる側もSwaggerHubアカウントを用意する必要がある

所感

よくないところの1で挙げた、「マージしてくれない」点が特にネックになってしまって、私達のチームの要望を満たすことはできないかなと感じました。
ただ、本記事では触れていませんがモックを気軽に使えたり、各種システム（GitHub、Amazon API Gateway、Lambda etc...）との連携ができたりと、シンプルなUIながら機能は充実しているため、天秤にかけてみてメリットの方が大きければアリなツールかと思います。