メインコンテンツへスキップ
見出し画像

API 仕様書を読み解くのは人間の仕事じゃなかった話

    TL;DR

    • 外部 API 連携の開発で最初に困るのは、難解な仕様書を読み解くこと

    • まともに RESTful で構築された API サービスはほぼない。仕様書は誤字脱字、整合性の欠如が当たり前

    • AI に仕様書を読み込ませ、サンプルと照合させると、人間が見落とす齟齬が次々見つかる

    • Excel で作られた仕様書を OpenAPI 形式に変換させると、以降の開発で AI が仕様を正確に参照できるようになる

    • 仕様書の読み解きは AI に任せて、開発者は「技術仕様に準拠した実装」に集中すべき


    開発者の仕事は仕様書を読むことじゃない

    プログラマの仕事は、特定の技術仕様に準拠したかたちでシステムを組み上げることです。API 連携なら、相手の仕様に沿ったリクエストを組み立て、レスポンスを正しく処理する。

    しかし現実には、その「仕様に準拠する」以前の段階で膨大な時間を取られます。仕様書を読み解く作業です。

    決済 API、旅行系 API、販売系 API、その他 Web サービスの API。仕事で外部 API を扱う機会は多いですが、開発者が最初にぶつかる壁は実装ではありません。仕様書の読み解きです。


    現実の API 仕様書

    ぶっちゃけた話、まともに RESTful で構築されている API サービスなんてほぼありません。

    よくある現実:

    • エンドポイントの命名に一貫性がない

    • GET で更新処理をしている

    • レスポンスの型が仕様書とサンプルで違う

    • 必須パラメータがドキュメントに書かれていない

    • 逆に、書かれているパラメータが実際には無視される

    仕様書自体の品質も問題です。

    • 誤字脱字が多い

    • パラメータ名と説明が別のエンドポイントのものになっている

    • バージョンが上がっても仕様書が追従していない

    • Excel で作られていて、検索もできない

    Excel で API 仕様書を作っているところ、まだまだ多いです。正直見にくい。そしてメンテナンスされているかも怪しい。


    AI に仕様書を読み込ませる

    ここで AI が活躍します。

    最初にやるのは、仕様書をそのまま AI に読み込ませることです。PDF でも Excel でも、テキストとして取り込めればいい。

    AI に仕様書を渡して「このAPIの全エンドポイントを整理して」と指示すると、構造化された一覧が返ってきます。この時点で人間が数時間かけて読み解く作業が、数分で終わります。

    ただし、これだけなら単なる要約です。AI の本領はここからです。


    サンプルとの照合で齟齬を発見する

    API の提供元がサンプルコードやサンプルレスポンスを用意している場合、仕様書と照合させます。

    AI に仕様書とサンプルの両方を渡して「仕様書の記述とサンプルの間に矛盾がないか確認して」と聞く。

    すると出てきます。

    • 仕様書では `user_id` が Integer と書かれているが、サンプルでは String で返っている

    • 仕様書に記載のないフィールドがサンプルレスポンスに含まれている

    • 必須パラメータとされているものが、サンプルリクエストでは省略されている

    • 日付のフォーマットが仕様書(ISO 8601)とサンプル(独自形式)で異なる

    人間が仕様書を読んで「正しいはず」と信じて実装し、結合テストで初めて気づく類の問題です。AI に照合させれば、実装を始める前に洗い出せます。


    Excel 仕様書を OpenAPI に変換する

    Excel の仕様書を読み込ませたら、次にやるのは OpenAPI(Swagger)形式への変換です。

    「この仕様書を OpenAPI 3.0 の YAML に変換して」と指示するだけです。

    これが効いてくるのは変換した瞬間ではなく、以降の開発です。

    • OpenAPI 形式にしておけば、以降 AI に「この API のエンドポイント X について」と聞くとき、仕様を正確に参照してくれる

    • Swagger UI で視覚的に確認できる

    • コード生成ツール(OpenAPI Generator 等)の入力にもなる

    • チーム内での仕様共有が楽になる

    Excel のシートを何度も見返す作業から解放されます。一度 OpenAPI に変換してしまえば、それが以降の「正」になる。


    実データとの乖離を修正する

    OpenAPI に変換した仕様がそのまま正しいとは限りません。元の仕様書自体が間違っている可能性があるからです。

    実際に API を叩いて、返ってきたレスポンスと OpenAPI 定義を照合します。

    ここでも AI が使えます。実レスポンスの JSON を渡して「この OpenAPI 定義と実レスポンスの差分を確認して」と聞く。

    • 定義にない新しいフィールドが追加されている

    • nullable と書かれていないフィールドが null で返ってくる

    • 配列と書かれているが、要素が0件のとき空配列ではなく null が返る

    見つかった差分を OpenAPI 定義に反映します。これで仕様書が「実態に即した仕様」に更新される。

    この OpenAPI 定義をベースに実装すれば、「仕様書を信じて書いたのに動かない」が起きにくくなります。バグが減るのはこの仕組みがあるからです。


    AI への指示の出し方

    この一連の作業で AI にどう指示を出しているか、具体的に書きます。

    仕様書を読み込ませるとき:

    この API 仕様書を読んで、全エンドポイントを以下の形式で整理してください:
    - メソッド + パス
    - 必須パラメータ
    - レスポンスの主要フィールドと型

    サンプルとの照合:

    以下の2つを比較して、矛盾点を列挙してください:
    1. API仕様書(上で整理したもの)
    2. このサンプルレスポンス: [JSONを貼る]

    OpenAPI 変換:

    この仕様書を OpenAPI 3.0 形式の YAML に変換してください。
    不明な点は仕様書の記述をそのまま採用し、推測した箇所にはコメントを付けてください。

    実データとの照合:

    この OpenAPI 定義と、実際のAPIレスポンスを比較してください。
    差分があれば、OpenAPI 定義側を実態に合わせて修正してください。

    ポイントは「何と何を比較するか」を明示することです。AI に丸投げで「仕様書チェックして」では精度が出ません。比較対象を2つ渡して「差分を出して」と聞くのが一番確実です。


    この方法で変わったこと

    導入前:

    • 仕様書を人間が読み解く(数時間〜数日)

    • 「たぶんこうだろう」で実装を始める

    • 結合テストで「仕様書と違う」が発覚

    • 修正して再テスト

    導入後:

    • AI に仕様書を読ませて構造化(数十分)

    • サンプル・実データとの照合で齟齬を先に洗い出す(数十分)

    • OpenAPI 定義を「正」として実装

    • 結合テストでの手戻りが激減

    特に減ったのは「仕様書を信じて実装したのに、実際の API の挙動が違った」というパターンです。仕様書と実態の乖離を実装前に潰しているので、当然の結果ではあります。


    まとめ

    • 外部 API 連携で最初に困るのは実装ではなく、仕様書の読み解き

    • 現実の API 仕様書は品質が低い。Excel 製で誤字脱字、整合性なしは当たり前

    • AI に仕様書を読ませ、サンプルや実データと照合させると、齟齬が実装前に見つかる

    • Excel 仕様書は OpenAPI に変換する。以降の開発で AI が仕様を正確に参照できるようになる

    • 開発者の仕事は仕様書を読み解くことではなく、仕様に準拠した実装をすること。読み解きは AI に任せる


    続編予告

    次回は、この「AI に何を渡して何を検証させるか」という設計の話を、もう少し大きな枠で書こうと思います。RAG や社内ナレッジ検索など、AI に食わせるデータの設計について。

    この記事が役に立ったら、フォローしていただけると励みになります。


    #API #AI #OpenAPI #エンジニア #開発効率化

    この記事が参加している募集

     
     
    Webサービスの企画・開発・運用会社の代表 / 現役フルスタックエンジニア 旅行・交通、在庫管理、金融など業種を横断したシステム設計と運用の実戦記録を発信 インフラ・バックエンド・フロント・AI(Claude)活用

    あなたへのおすすめ