この記事は Kyash Advent Calendar 2024 の5日目の記事です。
自己紹介
Kyashでサーバーサイドエンジニアをしているa1yamaです。
最近は盆栽にハマったり[1]、keyball39という自作キーボードで独自配列考えたり[2]しています。
業務では最近リリースされたKyashスポットマネーの開発をしたり、開発体験向上を考えたり楽しく開発しています。
今回話すこと
この記事ではこれまでKyashで管理されていたAPI Documentの改善施策の様子と実施したこと、これからどうしていくかをまとめていきます。
これまで
KyashではサーバーサイドエンジニアがAPIを作成してモバイルエンジニアがそのAPIを使ってKyashアプリの開発を行っています。
APIの仕様についてはMarkdownでまとめられたDocsを元にサーバーサーバーサイドエンジニアとモバイルエンジニアでコミュニケーションを取っていました。
モバイルメンバーとペインについてディスカッションしたところ以下のものが上がりました。
- 変数の小文字大文字やtypoのミスが発生する
- Nullabilityの問題が発生する
- Nullにならないと思ってたらNullだった
- 値がある or Null も扱いが違う
- 検索性
- パスで調べてもうまくヒットしないことがある
json形式で記載がされていたのでパラメータに対するコメントも分かりづらい状況でした。
また、使いたいAPIを調べたい際もモバイルエンジニアはGitHubを検索して調べていたそうですがうまく検索できないこともあったようでした。
以下はこれまでのMarkdownの記述例です。
パラメータの説明はあるものの、nullableの記載がjsonにあったり、例えばstatusがあった場合にstatusの一覧やstatusごとにレスポンスが変わった場合の表現が難しかったりしました。
※実際にこのようなAPIは存在しません
ツール選定
ペイン解消のためのツール選定を行う際にOpenAPIとProtobufが候補に上がりました。
Protocol Buffers（Protobuf）とは
Googleが開発した軽量かつ高速なデータシリアライズフォーマットです。
インターフェイス定義言語（IDL）としての役割として使われることもあり、今回はスキーマ定義に着目しての使い方で候補に上がりました。
gRPCと連携は考慮しないのであくまでスキーマ定義のみを記載するだけの想定です。
OpenAPIとは
RESTful APIを記述するための標準化された仕様です。
Swaggerという名前のほうが馴染みがある方も多いかと思います。
yamlまたはjson形式で記述されたファイルをAPIドキュメントとしてHTML生成した後にWeb公開される使い方が一般的で、Swagger UI、RedocといったツールでのAPIドキュメント生成があります。
選定基準
ツールのペイン解消は以下マトリクスにまとめました。
最終判断は自分に任せられたので、検索性の観点などを考慮してOpenAPIを採用しました。
Redocを使用してHTML出力して権限付きでの公開というところまで自動化すれば気軽にAPI仕様書が見れるというところも採用の理由となりました。
また、Redocの採用理由についてもペインに上がっていた検索性の向上を考慮しました。
ディレクトリ構造
分かりやすくするために一部変更しています
openapi/
├ components/
├ examples/
├ 関心事のディレクトリ/
├ schemas/
├ 関心事のディレクトリ/
├ paths
├ 関心事のディレクトリ/
├ openapi.yaml
少し細かく分かれていますが、openapi.yaml以外のファイルは小さくしたいという思いとSchemasの表示のためにこのようなディレクトリ構造になっています
ディレクトリ構造を考える上ではOpenAPI Specificationを参考にディレクトリ分割をしました。
$refを使用して各コンポーネントを参照することでopenapi.yamlの肥大化を抑えています。
分割方法は以下を参考にしました。
最初は以下のように関心事に合わせてドキュメント作成をしようとしましたが、一つのHTMLで管理できるようにと考えた結果openapi.yamlに集約するようにしました。
現在はひとつのプロジェクトでしか運用していないですが、他のプロジェクトや既存のdocsからの移行で変更する点があったら使いやすいように変更したいと思います。
この他に前述したHTML出力からWeb公開までに必要なスクリプト群やlintなどの設定ファイルがいます。
変化
今まではMarkdownにjsonで書いていたものから、型記載やnullable記載、コメントの記載、Exampleの記載などほしかったものが基本的に記載される形になりました。
ドキュメントの数が少ないので検索性の向上については分からないですが、検索窓があり検索することで必要なAPIが見つかるので、これから既存のドキュメントの移行を行うことでより使いやすいものになっていくかと思います。
APIの作成の前にドキュメントを書いてチームエンジニアでのレビューがあるのですが、レビューについてもやりやすくなりました。
json形式とは違い、各パラメータにコメントも書きやすくなった点でも「このパラメータに補足がほしい」などという要望にも答えやすくなったかと思います。
同時にAPI設計の部分で今まではUIを中心に話を進めて来ていましたが、スキーマ単位で会話出来るようにAPI設計をするようになりました。
「このUIを実現させるためのAPI」となると、汎用性が効かなくなるので、ドメインを抽象化してスキーマに落とし込むようにしました。
API設計とドキュメントの変更により、必要なAPIの設計が出来るようになったことが一番大きな変化になります。
これから
OpenAPIの採用で良い影響があったので、既存のドキュメントをOpenAPIに書き直していきたいです。
また、他のチームにもOpenAPIを使ってもらえるようにしていきたいです。
OpenAPIの旨味をまだまだ引き出せていないので、コードの自動生成やmock作成なども進めていきたいと考えています。
別で進めているAPIテストなどとの連携も含めて有効活用できるように開発体験の向上をこれからも進めていきたいです。
最後に
現在はこの他にも開発体験の向上を目指した施策をしています。特に今年は各チームで様々な変化がありました。
まだまだ良くなっていくKyashに少しでも興味がありましたら是非お声がけいただければと思います。
カジュアル面談は以下からお待ちしています。
それでは明日のKyash Advent Calendar 2024もお楽しみに〜！
デジタルウォレットアプリ「Kyash」を開発・運用しています。 もっとKyashを知りたいぞという方は、こちらもぜひご覧ください → blog.kyash.co/
Discussion