はじめに
業務でStoplight Studioを導入してOpen APIの管理をしているのですが、導入当初、Git連携時のエラーの解消で少々手間取ったので解決方法やGUI操作で吸収しきれない箇所について備忘録を残しておこうと思います。
Stoplight Studioとは
OpenAPI 定義ファイルの作成と管理ができる GUI エディタです。つまり画面の操作だけで簡単に API 定義が作れてしまうツールです。
最終的には yaml 形式でファイルを管理することになるので、 yaml を直接編集することも可能です。従って、大枠はポチポチと画面から定義していき、GUIで吸収できない所を直接 yaml をいじって実現するといった編集方法になります。
インストール
Web版、Macアプリ、Winアプリ、Linuxアプリがあります。
公式サイトより自身のOSに対応したインストーラーをダウンロードしてください。
基本的にソースコードをローカルに落としてAPI定義をするフローかと思うのでWeb版は使用しないと思います。
Git との連携方法 〜 commit の初 Push まで
Git との連携
アプリを起動したらOpen Git ProjectのGit URL欄に編集したいProjectのURLをペーストしてCloneします。
この際に GitHub アカウントを要求されるので、 自身のアカウント情報を入力してください。
パスワードを入力してSubmitをクリックした際に以下のエラーが表示されることがあります。
この場合は Personal Access Token を発行して入力してください。
Personal Access Tokenの発行方法についてはこちらが参考になります。
Clone に成功すると以下の画面が表示されます。ヘッダーの赤枠内に該当の Project名 / branch名 が表示されていれば OK です👍
Branch の切り替え
ヘッダーの Branch 名をクリックで Git Pull や Branch の切り替えができます。
Switch Branches をクリックで以下のダイアログが表示され、 Branch を切り替えることができます。「Choose a git branch to…」のところが入力欄となっており、こちらに任意の Branch 名を入力することで検索や新しい Branch を作成することができます。
Commit & Push
ファイルに変更を加えるとヘッダー左の Commit ボタンが活性化され、このボタンをクリックすると以下のダイアログが表示されます。
こちらから Commit Message や取り込む差分を選択して Push を押すとリモートの Branch に変更が取り込まれます。
初 Push の際に Author の情報が求められるので、GitHub のアカウント名とアドレスを入力してください。
Submit をクリックした際に以下のエラーが表示される場合があります。
これは Author が Github でアドレスを非公開にしていると発生します。
この場合は 代わりのアドレスを使用する ことができます。
2回目以降は以下から変更してください。
無事に Push が成功すれば以下の Meesage が表示されます。
GUI操作で吸収しきれない箇所について
コンフリクトの解消ができない
現状 Stoplight Studio 上からコンフリクトの解消はできないようになっています。
そのため普段使っているエディタなどを使用して解消する必要があります。
実際にOpenAPIを使ってAPI定義をされている方なら深く頷いていただけると思うのですが、yamlのコンフリクト修正って途轍もない苦痛が伴うんですよね...
可能ならば（というか絶対）yamlのコンフリクトは避けたいのですが、チームで開発していると複数機能を並行して開発している際などにどうしても発生してしまいます。
解決方法としてはチーム全体で開発情報を共有しつつ小まめにマージするか、yaml 自体を分割する運用が思い浮かぶのですが...
yamlを分割すると Stoplight Studio 上で API が表示されなくなる
これが2点目にして Stoplight を使う上で最大のネックだと思っています。
分割された yaml の API は GUI 上で表示されないので code を直接編集することになるのですが、それはもう他のエディタで編集するのと変わらないんですよね。
とはいえyamlってとても行数が膨らみやすくて、1ファイルにまとめようとすると簡単に万行を超えます。
そうなるとどんどん読み込みが遅くなったり、コンフリクト修正が地獄の様相を呈していくことになります。
（千行越えのコンフリクト修正する情景を思い浮かべてみてください、オェッってなると思います）
正直、自分はこの点に関して今も有効な解決案を見出せていません。もし何かいい考えや実際に行っている運用方法などがあればコメントいただきたいです m(_ _)m<ｵﾈｶﾞｲｼﾏｽ
まとめ
とはいえ定義すること自体はめちゃくちゃ楽になりました。Stoplight Studio 導入して良かったと思っています。
ポチポチクリックしてるだけAPIが定義できるのは、書き方を調べながら必死にコード書いていた時に比べて開発速度がダンチです。
辛いことも多々ありますが、それが Stoplight Studio を手放す理由にはなり得ないくらい依存しつつあります。
ストレスや悲しい思いのする人を少なくできるような運用方法を見つけたいなと思います。