API Documentの改善施策

Kyash Advent Calendar 2024 - 5日目

この記事は Kyash Advent Calendar 2024 の5日目の記事です。

自己紹介

Kyashでサーバーサイドエンジニアをしている a1yama です。

最近は盆栽にハマっていたり^[1]、自作キーボードのkeyball39で独自配列を考えたり^[2]しています。

業務では、Kyashスポットマネーの開発や、開発体験向上に取り組み、日々楽しく開発をしています。

今回話すこと

この記事では、Kyashで管理されていたAPIドキュメントの改善施策と実施した内容、今後の展望についてまとめます。

これまでの状況

Kyashでは、サーバーサイドエンジニアがAPIを作成し、それをモバイルエンジニアが利用してアプリの開発をしています。

API仕様はMarkdown形式でドキュメント化され、サーバーサイドとモバイルエンジニアの間でコミュニケーションが行われていました。

しかし、モバイルエンジニアとディスカッションを行った結果、以下のような問題点が浮かび上がりました：

- 変数の小文字・大文字やtypoによるミスが発生する
- Nullabilityに関する問題
  - Nullになると思わなかった値がNullになることがある
  - 値があるか、Nullかで動作が異なることがある
- 検索性が悪い
  - パスで調べても目的の情報がうまく見つからないことがある

特に、json形式で記述されていたため、パラメータに対するコメントが分かりづらく、nullableの取り扱いやエラーハンドリングも曖昧になりがちでした。

また、モバイルエンジニアはGitHubを検索して必要なAPIを調べていましたが、情報を見つけにくいこともありました。

以下は従来のMarkdown記述の一例です。この形式では、パラメータの説明やnullableの扱い、ステータスごとのレスポンスの変化などを正確に表現するのが困難でした：

※ 実際にこのようなAPIは存在しません

ツール選定

これらの課題を解決するため、適切なツールの選定しました。候補として挙がったのは、OpenAPI と Protocol Buffers（Protobuf） です。

Protocol Buffers（Protobuf）とは

Googleが開発した軽量かつ高速なデータシリアライズフォーマットです。

インターフェイス定義言語（IDL）としても使用され、今回はスキーマ定義に着目して活用することを検討しました。gRPCとの連携は考慮せず、あくまでスキーマ定義に限定した利用を想定しています。

OpenAPIとは

RESTful APIを記述するための標準仕様です。かつてはSwaggerという名前で知られており、今でもその名称に馴染みがある方も多いでしょう。

yamlまたはjson形式で記述されたファイルをAPIドキュメントとしてHTMLに生成し、Web公開することが一般的です。Swagger UIやRedocといったツールが代表的です。

選定基準

ツールの選定基準として、以下のようなマトリクスを用いて検討しました：

最終的には、自分の判断でOpenAPIを採用しました。その理由としては、検索性の観点や、Redocを使用したHTML出力による権限付き公開の容易さが挙げられます。これにより、API仕様書へのアクセスがスムーズになりました。

Redocの採用は、特に検索性の向上が大きなポイントでした。

Redoc公式サイト

ディレクトリ構造

分かりやすく管理するため、ディレクトリ構造を以下のようにしました：

openapi/
    ├ components/
        ├ examples/
            ├ 関心事のディレクトリ/
        ├ schemas/
            ├ 関心事のディレクトリ/
    ├ paths/
        ├ 関心事のディレクトリ/
    ├ openapi.yaml

ディレクトリを細かく分けることで、openapi.yaml以外のファイルのサイズを小さくし、管理しやすくしています。また、Schemasの表示にも配慮しています。

ディレクトリ構成を考える際は、OpenAPI Specificationを参考にしました。

各コンポーネントを$refで参照することで、openapi.yamlの肥大化を防いでいます。

分割方法は、以下のブログを参考にしています：
参考リンク

当初は関心事ごとに個別のドキュメントを作成しようとしましたが、最終的には1つのHTMLに統合する方針を採用しました。
参考リンク

現在は1つのプロジェクトでしか運用していませんが、他プロジェクトや既存ドキュメントの移行時には柔軟に対応する予定です。また、HTML出力やWeb公開に必要なスクリプト群、lint用設定ファイルも併せて整備しています。

変化

以前はMarkdownにjson形式で記述していたため、型の明示やnullable、コメント、例示（Example）の記載が分かりにくい状態でした。

OpenAPIに移行したことで、これらがすべて適切に記載できるようになり、ドキュメントの質が向上しました。

ドキュメント数が少ない現段階でも、検索窓の活用により必要な情報を簡単に探せるようになりました。今後、既存ドキュメントの移行が進むにつれて、さらに利便性が高まると期待しています。

API作成時には事前にドキュメントを作成し、チームエンジニアによるレビューを実施しています。各パラメータにコメントを記載できるため、「このパラメータに補足説明が必要」という要望にも対応しやすくなりました。

また、API設計の議論もスムーズになりました。これまではUIを基にした設計が中心でしたが、スキーマ単位での会話が増え、より汎用性のあるAPI設計が可能になりました。

これから

OpenAPIの採用によって得られた効果をさらに広げるため、既存のドキュメントをOpenAPIに書き直していく予定です。また、他のチームにもOpenAPIの導入を促し、全体的な開発体験の向上を図ります。

今後は、以下のような施策も検討しています：

• コードの自動生成
• モックサーバーの作成
• APIテストとの連携

これらを通じて、開発の効率化と品質向上を目指します。

最後に

現在、Kyashでは他にも開発体験の向上を目指したさまざまな施策を進めています。今年は特に大きな変化があった年であり、引き続き改善を続けていきます。

Kyashに興味をお持ちの方は、ぜひお気軽にご連絡ください！

カジュアル面談はこちらから

明日のKyash Advent Calendar 2024もお楽しみに！

脚注

1. 盆栽を育ててよかったこと

2. 独自配列を考える