概要
今回、2024年のアドベントカレンダーに投稿しようと思いこの記事を書いています。
レガシーなシステムやツールに苦しめられているエンジニアはたくさんいると思います。
この記事ではAPI仕様書をエクセルからOpenAPIに移行した際、どのような観点を持って取り組んだかを書いていきます。参考になれば幸いです。
取り組むきっかけ
モダンなAPI仕様書の管理ではOpenAPIを使うことが多いかと思います。
しかしながら、色々な経緯で未だにエクセルによってAPI仕様書を管理してるケースもあります。OpenAPIを使うメリットとして以下が挙げられます
- フォーマットを揃えることが出来る
- モックを簡単に用意することが出来て開発効率があがる
- API仕様書通りに実装されているかtestで自動検知できる
私のナレッジとしてこれらのメリットを十分に理解しており、これを使って組織やチームに貢献したいという思いが取り組みの始まりでした。
チームや組織としての視点と問題点
取り組みのバッドケースして、チームや組織という観点を見落としがちです。個人の経験談ではこれがベストと思っていても、チームとしての括りではどうか。チームではなぜ未だにエクセルでAPI仕様書を管理しているのか。
最初にAPI仕様書が作られたのは今から何十年も前でした。もちろんその頃はその方法がベストだったわけです。
まずはチーム内の色々な人にヒアリングをする事から始めました。
結果としては
- ドキュメント＝ワードorエクセルという既定路線があった
- 誰も改善する人がいないからなんとなくそのまま運用していた
という意見でした。え、意外とそんなものなの？！と驚くかと思いますが、レガシー問題の真相はここにあります。
結局のところチームの誰も手をつけたがらない＝他人事というのが真意なのです。
会社視点ではどうか
次に会社視点としてを考えてみます。会社の一員である以上、勝手に改善活動に動くわけには行きません（もしかしたらそんなフレキシブルな会社もあるかもしれないですが、、、）
- 移行スケジュールを建てる
- 必ずコストを比較する
- 事実をベースに提案をする
この3つは会社目線としてすごく大切になります。
特に既存のAPI仕様書の数が膨大な場合、移行にどのくらいかかるのか適正に会社に対して示す必要があります。
また提案には、個人的な感情は含めず、事実としてメリットやデメリットを示す必要があります。
今回のケースではAPI仕様書の数が多かったので、外部委託を利用する事にコスト削除する取り組みをしました。
移行手順の話
実際どのようにエクセルのAPIからOpenAPIに移行した手順です。
- エクセルのAPI仕様書からOpenAPI形式にツールを使って書き直す
- testを書きOpenAPIと連携し正しい形式が検証する
- お手本のPullRequestを作り外部委託と連携して数をこなす
- リプレイスが終わったものをEOLし告知する
エクセルのAPI仕様書からOpenAPI形式にツールを使って書き直す
まず一旦、エクセルのAPIを見ながらOpenAPIに変換していく作業を行いました。Stoplight Studioというツールを用いてOpenAPIの実装を行いました。こちらのツールはUIで直感的にAPI仕様書の記載ができます。
testを書きOpenAPIと連携し正しい形式が検証する
つぎにAPI仕様書が正しいかtestを使って検知するための仕組みを導入しました。
私の場合はRuby on Railsを使っていたので committee を使いました。
これにより、OpenAPI仕様書と実際のレスポンスが一致しているか検証できます。
RSpecに組み込む形で導入でき、一致していない場合RSpecが失敗するようになります。
お手本のPullRequestを作り外部委託と連携して数をこなす
また大量にリプレイスが必要になるので手戻りが発生した場合大変な事になります。そこで、お手本となるプルリクエストを作成し、一旦チーム内レビューを行い、後はそれと同じように単純作業で進められるように外部委託に協力していただきました。
リプレイスが終わったものをEOLし告知する
最後に、リプレイスが終わったエクセルに対しては何かしらでもうここには追記しないで欲しいという旨を示すことが大事です。またチームに対して告知する事も重要です。
これをしておかないと知らない人たちが無駄にエクセルにAPI定義を追加してしまうという元も子もない事が起こります。
まとめ
このケースではAPI仕様書の話になりましたが、誰しもが働いていて「自分が知っている知識だったらこうするのに」という違和感を感じた事はあると思います。
もちろんレガシーな環境に文句を言うだけなら簡単です。（もちろん、このクソシステムは、、、とか愚痴は言いますよね。笑）
その次のステップとして、いかに行動に移すか、組織としての課題をいかに自分ごととして捉えていくか。
また自分だけでなく、チームをうまく巻き込んで問題の解消に動けるか。
レガシーな問題に取り組むにおいてはその視点がすごく大切になってくると思います。
レガシーな問題に取り組むのは勇気がいりますが、むしろ、この経験をもとに個人からチームや組織、会社視点を持つことによってステップアップできる。また貢献できる喜びを知るというところが大きいと感じています。