OpenAPI Specificationを導入するまでの苦労と失敗、その後の効果

はじめに

ラクスフロントエンド開発2課の斉藤です。

ラクスの開発するプロダクトである楽楽明細、楽楽電子保存、楽楽請求ではOpenAPI Specification（以下OAS）を採用した開発を行っています。
今でこそOASを活用した開発を行うことができていますが、導入にあたっては様々な苦労がありました。
そこで今回は

1. 何故OASを導入したのか
2. 導入にあたってどのような課題があったのか
3. 導入して実際に効果はあったのか

を紹介したいと思います。

対象読者

• OASの導入を検討している人
• OASの導入に周りから賛同を得られない人
• OAS導入の効果が知りたい人

TL;DR

時間がない方に向けて結論から書きます。

1. 従来のAPI仕様書の閲覧パフォーマンスやコミュニケーションの齟齬による課題を解決したくてOASを導入した。
2. 導入にあたってはステークホルダーの不安をヒアリングし、ケアをすることで合意を得る事ができた。
3. OAS導入後、開発者の満足度は高く、工数削減の効果があった。またAIと組み合わせる事で生産性がさらに向上する副次効果もあった。

OpenAPI Specificationとは

OASとはRESTful APIを定義するための標準仕様であり、もともとはSwaggerと呼ばれていました。*1

JSONまたはYAML形式で記述され、APIのエンドポイント、HTTPメソッド、パラメータ、レスポンス、エラーハンドリング、などを定義することができます。

例えば以下はYAML形式で記述されたOASの例です。

openapi: 3.0.2
servers:
  - url: /v3
info:
  description: |-
    This is a sample Pet Store Server based on the OpenAPI 3.0 specification. 
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'

これをSwagger UIのようなツールを用いて表示すると、以下のようにシンプルなUIでAPI仕様を確認することができます。

公式がサンプルを用意しているので、こちらを参照するとより具体的な使用イメージが掴めると思います。

OASを導入することの何が嬉しい？

OASを導入する前、プロダクト開発チームはAPI仕様書について以下の課題を抱えていました。

1. プロダクトごとにAPI仕様書を記述するツールやフォーマットがバラバラでスイッチングコストがかかる

例えばあるプロダクトではAPI仕様書の記述にスプレッドシート、他のプロダクトではGoogle Docs、といったようにそれぞれが異なるツールを用いていました。
記述のフォーマットも統一されておらず、複数のプロダクトを横断的に開発するチームにとっては記述ルールの学習コストが無視できないものになっていました。

2. 記述量が増えると動作が重くなる

これはGoogle Docsを採用しているプロダクトで顕著だったのですが、APIのエンドポイントが増えるにつれ動作がカクカクしてしまい、閲覧するにも一苦労という状況が生まれていました。
これに対してはドキュメントを分割するなどの対策が取れますが、複数ファイルを参照しながら開発するのは良い体験とは言えませんでした。
API仕様は何度も繰り返し参照するドキュメントなので、閲覧時のパフォーマンスは早急に改善したいポイントでした。

3. API仕様変更の伝達漏れの多発

開発する中でAPI仕様の変更はつきものです。（...ですよね？）
大きな変更は滅多にありませんが、軽微な変更、例えばプロパティ名をより適切な命名に変更したり、エラーパターンを追加したりといったことはあります。
そういった変更の共有漏れが頻発し、疎通テストで初めて発覚して慌てて修正するといった状況が多くありました。
コードの修正は開発工程の初期であるほど低コストで済みます。
修正が起きた都度、チーム内で変更が共有されている状況を作る方法を模索するも最適解が出ない状態でした。

---

これらの課題を全て解決したいと考えたとき、OASが選択肢として挙がりました。

OASを用いると

1. 仕様の記述フォーマットが規定されているため、チーム内で共通言語を用いた横断的な開発ができる
2. Swagger UIのようなツールを用いれば多量のAPI仕様を１つのHTMLで高いパフォーマンスで閲覧できる
3. OASからI/Fの型を自動生成することで型レベルで伝達漏れを防ぐことができる

といったメリットがあり、自分たちの抱える課題を一挙に解決するできるのでは？という期待から、導入検討に進むことになりました。

導入までの課題

OASを使えば課題解決できるヤッター導入しま〜す！あとよろしく、で通ったら苦労しません。
私たちはチームで仕事をしているので、ステークホルダーと合意形成をする必要があります。
また、弊社が規定するラクスリーダーシッププリンシプルという行動指針に全体最適視点を持つというものがあります。
この指針に照らし合わせ、OAS導入が全体最適に寄与するという仮説をチームから納得してもらう必要がありました。
そこで各々のプロダクトを担当するバックエンドエンジニアと会議を行い、OASの概要と導入を検討していることを伝えました。

中にはぜひ導入したいというエンジニアもいれば、いきなり変えるのには不安がある、といった意見もありました。
さらに深掘って、導入にあたっての疑問点や不安に思っていることをヒアリングすると以下の意見が挙がりました。

1. OAS導入のメリットは理解できたが、開発フローがどのように変わるかイメージできない
2. OAS導入によって自分が行うタスクがどう変わるのかイメージしづらい
3. OASはフォーマットが規定されているため、学習コストが気になる

そこで1, 2に関してはOAS導入の前後で変わることをスライドを用いて説明することでイメージを掴んで頂きました。
また3に関しては勉強会を開催すること、スプレッドシートで書かれた既存のAPIをOASに書き換え、記入例を示すことで対応しました。
その甲斐あってか最終的には導入を提案した3つのプロダクト全てにおいて、合意を得ることができました。
合意形成がうまくいったポイントとしては相手が不安に思っていることをヒアリングし、その不安は杞憂である、もしくは対応策があることを根拠を持って答えることができた点かと思っています。
と、さらっとスマートに事が運んだかのように書いていますが、最終的に合意形成に至るまでに３ヶ月くらいかかっています。

理由としては

1. OASの調査に時間をかけすぎたこと
2. OASのデメリット全てに対応策を講じようとしてしまったこと

が挙げられます。

1. OASの調査に時間をかけすぎた

OASの調査にあたり公式ドキュメントを読み込んでいたのですが、覚えるべき事が膨大でOpenAPIを書けるようになるまでにはかなりの時間がかかるのでは？と考えるようになっていきました。
フロントエンドエンジニアだけで完結するならまだ良かったのですが、いずれはバックエンドチームにもOpenAPIを書いてもらうようにしたかったので、学習コストを理由に導入を断られてしまう不安がありました。
そこでStoplight StudioやApicurio StudioといったGUIでOpenAPIを記述できるようなサービスを使えば学習コストを抑えられそうと思い至り、さらにそちらの調査にも時間を割いてしまいました。

結論から書くと、現在これらのツールは使用していません。
OASを導入した今言えることは、そもそもOpenAPIの学習コストは高く無いということです。
OpenAPIは様々なAPI仕様記述のフォーマットを用意していますが、使用するのはその中の一部であり、公式が用意しているドキュメントを真似ればすぐに書けるようになります。
また弊社ではGithub Copilotを全社的に導入しており、CopilotはOASの推論がとても得意なので、知識が浅いうちでも強力なサポートを得る事ができます。

したがって、学習コストを下げるためにGUIツールを導入するというのはコストと効果が見合っていないと判断しました。
実際、バックエンドに対して不安をヒアリングしたときに学習コストの懸念は挙がったのですが、先述したようにちょっとした勉強会の開催と記入例の提示で納得していただけました。
ドキュメントを読んだ印象だけで学習コストが高いと決めつけ、あれもこれもと調査に時間を使ったのはもったいなかったです。

2. OASのデメリット全てに対応策を講じようとしてしまったこと

OASを調査していく中でスプレッドシートやGoogle DocsにはできてOpenAPIにはできないことがいくつかある事がわかりました。
例えばスプレッドシートやGoogle Docsはドキュメント同士をリンクすることができたり、記述した内容に対するコメント等ができますが、OpenAPIではできません。
そこで、OpenAPIのdescriptionをうまく活用する事でどうにかデメリットを吸収できないかと思索していました。

結局今はdescriptionの記述ルールなどは特に設けずに運用しています。
ドキュメント同士のリンクなどはできれば便利ですが、必須な機能ではありません。
これを無理やり実現しようとして運用コストが高くなっては本末転倒です。
新しい手法を導入する事でメリットとデメリットの両方が生じるのは当然です。
生じるデメリットが本来解決したかった課題の大きな障害となるかどうかという視点で、対応の要否を最初から取捨選択しておくべきでした。
実際このようなデメリットが存在することを伝えつつOAS導入をチームに提案しましたが、すんなり受け入れてもらえました。

---

振り返ると、２つの失敗の共通点は思い込みだったと思います。

• 学習コストが高いのではないか？
• デメリットに対する完璧な対応策を考えておくべきではないか？
• これらに対処しなければ合意をもらえないのではないか？

このような思い込みを根拠にした意思決定が、多くの時間をかけてしまった原因だったように思います。
次に同じような課題に直面した際は

• ある程度調査したら実際に手を動かしてシミュレーションしてみる
• 早い段階でチームに相談しデメリットが許容できるものか認識を擦り合わせておく

ことで思い込みによる無駄を避けるように行動していきたいと思います。

導入して１年、開発環境は改善されたのか？

OASを導入してから約１年経った現在（2024/08）は以下の流れで開発を行っています。

1. フロントエンドエンジニアがOpenAPIでAPI要求仕様を記述しプルリクエストを出す
2. バックエンドエンジニアがAPI要求仕様のレビューを行い、API仕様を確定させる
3. OpenAPIから型やコードを自動生成する（フロントエンドはopenapi-generatorを使用）
4. 生成した型をパッケージ化しプライベートレジストリにpublish
5. npm installで生成した型をインストールしI/Fを実装

フロントエンドもバックエンドもOpenAPIから自動生成した型やコードを使用しているので、疎通テストのバグが大幅に減少し工数削減となりました。
また自動生成した型とGithub Copilotを組み合わせて、モックデータを推論できるという副次効果の恩恵にもあずかっています。
もちろん当初挙げていた課題も解決する事ができ、開発体験も改善されました。
さらに今回エンジニアに向けてOASを導入して実際にどう感じているか、アンケートを取ってみたので結果を紹介したいと思います。

---

回答者の属性：OAS導入後、OpenAPIを参照もしくは記述したことがあるエンジニア
有効回答数：9件

Q: OpenAPIを使った開発において、改善が必要だと感じた点や課題を教えてください。
A: 実装過程の後半でSwaggerの修正に少しハードルを感じていますので、FE/BE共に修正が必要なら早急に相談し、すぐ修正するコミュニケーションや雰囲気をお互いで作っていきたいと思っています。

Q: その他ご意見ご感想などあれば記述してください。
A: 導入当時、OpenAPIを導入したい経緯や課題は理解できたが、既存の開発プロセスのどこで何をすればよいのかはよくわからなかった。今でも正しく理解できているか微妙。

---

全体的に高い満足度であり、少なくとも定性的にはOAS導入の効果はあったと言えそうです。
ただ、OASの導入プロセスについては不満と回答した方はいないものの、他の項目と比べると満足度が低めです。
自由記述の回答にもある通り、「開発プロセスのどこで何をすればよいのかはよくわからなかった。」と意見を頂いており、スライドによる説明だけでは伝わりづらかった部分があったと考えられます。
小さくプロトタイプのリポジトリを作って、OAS導入後の開発プロセスのシミュレーションを行うなどすればより理解して貰いやすかったのかなと思います。

おわりに

本記事ではOAS導入に至った経緯から導入までの課題、その後の効果まで紹介しました。
導入までには数々の障害があり、至らない部分も多くありましたがなんとか開発フローに組み込む事ができました。
全体としては高い満足度となり、当初の課題も解決できたため導入してよかったと感じています。
今後さらなる開発プロセスの改善に取り組む際には、今回の反省点を活かし、より効率的に、より多くのステークホルダーに納得していただけるよう進めていきたいです。

*1:曖昧な情報です。おそらくOpenAPI2系まではSwagger, 3系からはOASと呼ばれています。