Stoplight StudioでGitとの連携 〜 初Pushまで

# はじめに
業務でStoplight Studioを導入してOpen APIの管理をしているのですが、導入当初、Git連携時のエラーの解消で少々手間取ったので解決方法やGUI操作で吸収しきれない箇所について備忘録を残しておこうと思います。

# Stoplight Studioとは
OpenAPI 定義ファイルの作成と管理ができる GUI エディタです。つまり**画面の操作だけで簡単に API 定義が作れてしまうツール**です。

最終的には yaml 形式でファイルを管理することになるので、 yaml を直接編集することも可能です。従って、**大枠はポチポチと画面から定義していき、GUIで吸収できない所を直接 yaml をいじって実現する**といった編集方法になります。

# インストール
Web版、Macアプリ、Winアプリ、Linuxアプリがあります。
[公式サイト](https://stoplight.io/studio)より自身のOSに対応したインストーラーをダウンロードしてください。

基本的にソースコードをローカルに落としてAPI定義をするフローかと思うのでWeb版は使用しないと思います。

# Git との連携方法 〜 commit の初 Push まで
## Git との連携

アプリを起動したらOpen Git ProjectのGit URL欄に編集したいProjectのURLをペーストしてCloneします。
![スクリーンショット 2022-09-25 14.57.14.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/8cba6a1d-2756-87ba-86e0-a182a2590585.png)



この際に GitHub アカウントを要求されるので、 自身のアカウント情報を入力してください。
![スクリーンショット 2022-07-15 15.02.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/55a17818-3d96-96a7-ba52-373c01503e64.png)


パスワードを入力してSubmitをクリックした際に以下のエラーが表示されることがあります。
この場合は Personal Access Token を発行して入力してください。
Personal Access Tokenの発行方法については[こちら](https://qiita.com/kz800/items/497ec70bff3e555dacd0)が参考になります。
![スクリーンショット 2022-07-15 15.37.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/3f74c477-61ae-dee4-ddd2-56fe8890adf1.png)


Clone に成功すると以下の画面が表示されます。ヘッダーの赤枠内に該当の Project名 / branch名 が表示されていれば OK です👍
![スクリーンショット 2022-09-25 15.09.32.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/68749ce3-f1c3-3baa-9bee-b88c1e55a8f5.png)

## Branch の切り替え
ヘッダーの Branch 名をクリックで Git Pull や Branch の切り替えができます。
![スクリーンショット 2022-09-25 15.09.38.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/334e9ba5-e7f3-8df6-10eb-1ac07f95befb.png)

Switch Branches をクリックで以下のダイアログが表示され、 Branch を切り替えることができます。「Choose a git branch to…」のところが入力欄となっており、こちらに任意の Branch 名を入力することで検索や新しい Branch を作成することができます。

![スクリーンショット 2022-09-25 15.09.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/4ac1c926-6216-6c8a-2be6-37ff0e872ef9.png)

![スクリーンショット 2022-07-15 15.57.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/0f3956e2-2b7b-7a2a-c635-d9958c62a0b6.png)

## Commit & Push
ファイルに変更を加えるとヘッダー左の Commit ボタンが活性化され、このボタンをクリックすると以下のダイアログが表示されます。
こちらから Commit Message や取り込む差分を選択して Push を押すとリモートの Branch に変更が取り込まれます。
![スクリーンショット 2022-09-25 15.11.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/189327a2-1975-7fc8-2d38-e97b93b133e7.png)


初 Push の際に Author の情報が求められるので、GitHub のアカウント名とアドレスを入力してください。
![スクリーンショット 2022-07-15 16.16.29.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/5892cf2f-b0b5-6265-b913-3d90d8a996f4.png)


Submit をクリックした際に以下のエラーが表示される場合があります。
これは Author が Github でアドレスを非公開にしていると発生します。
この場合は [代わりのアドレスを使用する](https://qiita.com/Canon11/items/e6f64597d82dbf88f75f) ことができます。
![スクリーンショット 2022-07-15 16.18.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/d2917f71-363c-1a9c-6b55-69121186231d.png)

2回目以降は以下から変更してください。
![スクリーンショット 2022-09-25 15.15.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/72d0262c-d157-ccc3-5415-985c59f58aa0.png)

無事に Push が成功すれば以下の Meesage が表示されます。
![スクリーンショット 2022-07-15 16.27.59.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2282374/bbe08e16-c5cb-c3c1-701d-5776d99da7aa.png)

# 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 を手放す理由にはなり得ないくらい依存しつつあります。
ストレスや悲しい思いのする人を少なくできるような運用方法を見つけたいなと思います。