OpenAPI

どのようなものか

OpenAPIは、HTTP
APIを呼ぶ側が知るべきすべて、つまりアドレス、操作、入力、出力、エ
ラー、セキュリティーを、人もプログラムも読める、一つのJSONまたはYAML
ファイルに記す標準形式です。標準自体をOpenAPI
Specificationと呼び、OASと略すことが多く、それに従ったファイルが
OpenAPI記述です。元はSwagger
Specificationという形式で、Swagger UIなど、周辺のツールには以前の名
前が残っています。

仕様は、「HTTP
APIのための、標準的で、プログラミング言語に依存しないインターフェー
ス記述」を定めると説明します。目標は、人やプログラムが、ソースコー
ド、追加のドキュメント、ネットワーク通信のキャプチャーなしで、サービ
スの機能を理解できることです。入口となる文書名には、`openapi.json`か
`openapi.yaml`を推奨し、大きな記述は、参照でつないだ複数のファイルに
分けることもよくあります。

Swagger 2.0は2014年9月に公開され、2015年12月31日にOpenAPI
Initiativeへ寄贈されました。新しい名前での3.0.0は2017年7月、3.1.0は
2021年2月、3.2.0は2025年9月に続きました。

記述の最上位には、いくつかの要素があります。`info`はAPIの名前とバー
ジョン、`servers`は動かす場所を示します。`paths`は各アドレスを持ち、
その下に、HTTPメソッドごとの操作と、パラメーター、リクエストボ
ディー、想定する応答を置きます。`components`は、データのスキーマ、パ
ラメーター、応答、呼び出し側の認証方法を定めるセキュリティースキーム
など、再利用するものをまとめます。3.1以降は、`webhooks`で、APIが利用
側へ送るリクエストも記述できます。最小限の断片は、次のようになりま
す。

```yaml
openapi: 3.1.0
info:
    title: Orders
    version: 1.4.0
paths:
    /orders/{id}:
        get:
            operationId: getOrder
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                "200":
                    description: One order
```

データの形は、スキーマ言語で書きます。3.1以降のSchema Objectは、JSON
Schema Draft
2020-12の上位集合です。3.0は、以前の草案の一部を基に、独自の追加を加
えたものでした。JSON
Schemaが一つのデータを記述するのに対し、OpenAPIはHTTP API全体を記述
し、各部分にはJSON
Schemaを借りて使います。隣接する仕様は、別の種類のインターフェースを
記述します。AsyncAPIはメッセージ駆動のシステムを扱います。gRPCのサー
ビスはProtocol
Buffersの`.proto`ファイルで宣言し、GraphQLサーバーは自身のスキーマを
公開します。

なぜ重要なのか

標準形式の記述は、多くのツールが読める一つのファイルであり、それぞれ
が、チームの手作業を減らします。参照ドキュメントを生成できます。複数
の言語のクライアントライブラリーも生成でき、フロントエンドはURLを組
み立てる代わりに、型付きの関数を呼べます。モックサーバーも記述を基に
応答するため、バックエンドができる前にフロントエンドを作れます。ゲー
トウェイはルートを取り込み、テストスイートは記述に照らして通信を検証
し、APIを呼ぶAIエージェントは、何が使えるかを知るために読みます。

その広がりは、リスクでもあります。すべてのツールが、そのファイルを信
じます。間違った記述は、ないより悪いものです。生成したクライアントは
コンパイルでき、ドキュメントには権威があるように見える一方、問題が表
れるのは、他者の製品の実行時だからです。

そのため、大きな判断は、記述をどこから作るかです。設計先行では、人が
記述を書き、契約としてレビューして、それに合うサーバーを実装します。
コードを書く前にAPIの形を議論でき、公開APIや、並行して作業するチーム
に向きます。代償は、記述とサーバーという二つのものに、食い違いが起こ
り得ることです。コード先行では、サーバー自身の型と注釈から記述を生成
します。サーバーにないルートは記述できませんが、その型で表せる範囲を
超える精度は得られず、設計の議論は文書でなくコードレビューで行いま
す。どちらも、ビルド時に検査して初めて、記述の正しさを保てます。

3.0から3.1への移行では、3.1がJSON Schema
2020-12を採用したため、スキーマの書き方が変わりました。ジェネレー
ター、バリデーター、ゲートウェイが対応するバージョン範囲は、それぞれ
違います。そのため、チームが書けるバージョンは、処理の連鎖の中で最も
古いツールに制約されます。

実際の活用例

初めは、一つのAPIをFiberで動かし、エンドポイントごとに手で検証を書
き、全体の形を記述する単一の文書はありませんでした。HTTP層を、Fiber
上のHuma
v2へ移しました。各エンドポイントを、入力と出力の構造体で宣言し、その
型からOpenAPI記述を生成します。ドキュメントは、Wikiで古くなるのでな
く、コードに追随します。二つのWebSocketエンドポイントは、Humaのリク
エストと応答のモデル外なので、素のFiberに残ります。記述が重要になる
のは規模のためです。649パスに760操作あると、実際には、この記述だけが
API全体を読み解く方法になります。操作が五十だったとき以上に、記述が
完全かどうかが重要で、CIの検査がルートの一致率を100%に保ちます。

別のプロジェクトでは、記述は、データベースから外へ伸びる連鎖の中間に
あります。データベースのスキーマと関数がGoの型を形作り、Humaが記述を
出し、フロントエンドが使うものを、そこから生成します。44,076行の型付
きTypeScriptクライアント、フロントエンドのテスト用の61のモックハンド
ラー、各フォームが適用する制限です。フロントエンドとバックエンドのず
れは、食い違ったまま公開した後、ブラウザーの422として現れがちです
が、この連鎖で対処します。CIの契約検査は、ずれがあればビルドを失敗さ
せます。検査対象には、「欠落」と「null」を混同しやすいボディーの任意
フィールドと、クエリーパラメーターの列挙値を含めます。代償は、すべて
の間に生成処理が一段入り、連鎖全体の信頼性が、最も保護の弱い部分に制
約されることです。

AIエージェントが利用できる状態についての自社ページも、同じ考えをエー
ジェントに適用します。エージェントが使えるアプリケーションは、記述済
みのAPIを提供します。OpenAPI文書、エージェントから直接呼ばせるべき場
合のMCPサーバー、パスワードを渡さず利用者の代わりに動くためのOAuthメ
タデータです。ページは、勧告をそのまま守るのでなく、一つずつ分類して
います。自社サイトにはAPIがないため、APIカタログとOAuthメタデータ
は、そこで採用しなかった五つのうちの二つです。

問題が起きるところ

サーバーが行わないことまで、記述が約束します。
手で保守する記述は、追加したクエリーパラメーター、名前を変えたフィー
ルド、サーバーだけが知るエラーコードなどに、追い付かなくなります。生
成クライアントは、その架空の仕様に合わせてコンパイルされます。コード
から記述を生成するか、別に保ち、テストスイートで、実際のリクエストと
応答を記述に照らして検査します。サーバーが登録するルートと、記述が並
べるパスも比較します。

クライアントを再生成するたびに、半分のメソッド名が変わります。
`operationId`がなければ、ジェネレーターは、パスとHTTPメソッドから名
前を作ります。ルートを移すと、すべての呼び出し側が使う関数名が変わり
ます。仕様は、各`operationId`が一意であることを求め、大文字と小文字
を区別します。すべての操作に付け、公開関数名と同じ注意を払って選び、
一つでも欠けたら、リンターでビルドを失敗させます。

更新後、nullを許すフィールドが、nullを拒否します。 OpenAPI 3.0は、
`nullable:
true`で指定していました。3.1では、そのキーワードがなくなり、型はリス
トになります。バリデーターは、知らないキーワードを通常無視するため、
3.0のスキーマを3.1と付け替えただけでは、作者が許したつもりのnullを拒
否します。`exclusiveMinimum`が数値になる変更も含む、OpenAPI
Initiativeの移行ガイドに従って変換します。

```yaml
i# OpenAPI 3.0		engineer.company	70
type: string
nullable: true
i---		engineer.company	70
i# OpenAPI 3.1		engineer.company	70
type: [string, "null"]
```

例が、自分のスキーマに合いません。
仕様は、例はスキーマに合うべきとし、検査をツールに任せます。読者がド
キュメントからコピーすると422を受け、モックサーバーが返した例を基
に、実際のAPIが拒否するデータでフロントエンドを作ってしまいます。CI
で、すべての例を、本番の通信と同じ厳しさで検証します。

公開した記述が、管理APIを案内します。
全ルートから生成した一つの記述を公開アドレスで配ると、内部の操作とそ
のスキーマを、誰でも読めます。利用対象ごとに、内部の操作を除外した記
述を生成して公開します。仕様は、まさにこの種のアクセス制御のために、
オブジェクトを空のままにしたり、削除したりすることを認めます。

参考資料

  * OpenAPI仕様 — すべてのオブジェクトとフィールドの定義、および各版
の履歴を含む、標準の最新版です。

  * JSON Schema Draft 2020-12 — OpenAPI
3.1以降が、各リクエストと応答のボディーに使うスキーマ言語です。

  * OpenAPI 3.0から3.1への移行 — `nullable`など、スキーマの変更をま
とめた、OpenAPI
Initiative自身の一覧です。

  * Huma：OpenAPI生成 — 上のプロジェクトで使うGoフレームワークが、ハ
ンドラーの型から記述を作る方法です。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/openapi/	engineer.company	70
