Tsuzura

OpenAPIでAPI仕様を作る

承認済み要件から一つのAPI処理を切り出し、入出力、Schema、セキュリティ、未決事項を空欄票に整理します。

公開日
更新日

OpenAPIでAPI仕様を作るときは、承認済み要件からAPIの処理を一つ選びます。入力、成功時・エラー時の返却内容、認証・認可の要件をまとめます。本記事では、システムがHTTPを使って別のシステムの処理を呼ぶ仕組みをHTTP APIと呼びます。呼び出す側が送る情報をrequest、結果として返る情報をresponseと呼びます。また、呼び出し元がどの利用者またはシステムかを確認することを認証、その呼び出し元に対象の処理を許すか決めることを認可と呼びます。

APIという言葉や、一回の依頼と返答の関係から確認したい場合は、先にAPIとは？システム同士の頼み方と返し方で一往復を整理します。

まず、呼び出し先を示すpath（サーバーURLより後ろの相対パス）と、呼び出しの意味を示すHTTPメソッドを決めます。この組を、本記事ではoperationと呼びます。

OpenAPIは、HTTP APIの機能を人とコンピューターが理解するための、プログラミング言語に依存しないインターフェース記述です。OpenAPI Specification 3.2.0は、ソースコードや通信内容を調べなくてもサービスの機能を理解できるようにする仕様だと説明しています。以下、OpenAPI SpecificationをOASと表記します。Tsuzuraでは、OpenAPIに記述する内容を「外部から確認できる契約」と整理します。実装コードや業務要件そのものではありません。

開始条件は、要件と受入条件が承認され、契約を維持する責任者が決まっていることです。完了時には、一つのoperationを空欄の作成票へ記録します。レビュー担当者が、実装へ渡せるか、HOLDにするかを判断します。HOLDとは、推測で先へ進めず、再判断に必要な情報と責任者を残す状態です。

ここで挙げる役割は役職名ではなく、引き受ける責任です。契約の責任者はソースと版を保守し、変更記録を残します。レビュー担当者は要件との対応と検証結果を確認し、最終採否者は残るリスクを受け入れるか決めます。セキュリティ担当者はデータと認証・認可を確認します。ツールで信頼して扱える範囲も同じ担当者が確認します。組織の承認ルールが許せば兼任できます。兼任した役割と判断根拠は記録します。組織のルールで独立確認が必要なら、執筆者だけで採否を決めません。機微データや権限を扱う場合も同様です。第三者文書やコード生成物の実行を扱う場合も、執筆者だけで決めません。該当分野を確認できる担当者がいなければHOLDです。

認証・認可方式の詳細やOAuth・OpenID Connectは扱いません。業務エラーの完全な分類とAPI全体のバージョン戦略も対象外です。ゲートウェイ設定とフレームワークのコード生成も扱いません。配備と完成済みのOpenAPI文書も対象外です。

本記事は、OpenAPIを使って契約を管理すると決めた後に使います。採用が未決なら、技術選定の条件へ戻り、同じ契約を複数の人やツールが使うか、OASを処理するツールが必要か、責任者が版を保守できるかを確認します。OASを必要とするツールがなく、同じ作成票の項目と変更履歴を承認済みの別形式で管理できるなら、OpenAPIを使わない判断もできます。APIの大きさだけでは決めません。文書を保守する責任者や対応ツールを決められないなら、作成を始めずHOLDにします。これはTsuzuraの採用判断であり、OASの規範要件ではありません。

仕様の版とツール対応を分ける

OpenAPIの仕様版、Schema（データの構造と制約を表す規則）を解釈するdialect、ツールの対応状況は別々に記録します。ここでいうURIは、dialectや参照先を識別する文字列です。2026年8月20日時点で、OpenAPI Initiativeによる最新の公開済み仕様版は3.2.0です。版を固定した3.2.0の規範本文と公式の公開版一覧で確認できます。

固定するもの 記録する値 役割 確認方法
OpenAPI Specification openapi 文書が使うOASの機能範囲 OpenAPI Initiativeの版固定仕様を開く
OpenAPI Documentの版 info.version 一つのOpenAPI Documentの変更版 文書の版管理規則と変更記録を確認する
Schema dialect jsonSchemaDialectまたはSchemaリソースの最上位に置く$schema Schemaキーワードの解釈 dialect URIと使用キーワードを確認する
ツール対応 ツール名・版・対応OAS・対応dialect 読み込み、表示、検証、生成ができる範囲 公式の対応情報と最小検証で確かめる

OASではmajor.minorが機能範囲、patchが誤りの修正または明確化を表します。openapiはOASの版です。info.versionはOpenAPI Documentの版であり、APIの版、OASの版、複数文書で構成するOpenAPI Description全体の版とは別です。

OAS 3.2.0のSchema ObjectはJSON Schema Draft 2020-12を拡張したものです。既定のOAS dialectを示すURIは次の値です。

https://spec.openapis.org/oas/3.1/dialect/base

数字の見た目をそろえず、OAS 3.2.0のSchema Objectとdialect指定をそのまま記録します。

OpenAPI 3.2.0を選んでも、採用ツールが全フィールドを扱えるとは限りません。仕様には任意の機能や実装依存の動作があります。作成側と利用側のツール、変更のたびに自動検査するCI、文書表示、コード生成が必要な範囲を扱えると確認できなければHOLDです。

pathとHTTPメソッドでoperationを決める

本記事で扱うPaths Object内では、相対pathとHTTPメソッドの組で一つのoperationを特定します。Paths Objectはエンドポイントへの相対pathを持ち、Path Item Objectは利用できるoperationをメソッドごとに記述します。OAS 3.2.0のPaths ObjectとOperation Objectが規範です。

  1. 承認済み要件から、一回のリクエストで達成する利用者の目的を一つ選びます。
  2. 対象リソースと識別方法を確認し、相対pathを決めます。システム境界が不明ならC4モデルの構成図、呼び出し順が不明ならシーケンス図へ戻ります。
  3. HTTPメソッドは処理名の好みではなく、リクエストの意図に合うものを選びます。RFC 9110のメソッドの意味では、メソッドがリクエストの意味を決める主な情報源です。
  4. operationの目的、開始条件、成功条件、外部への作用、責任者を一文ずつ書きます。分からない項目をpathやメソッドの推測で埋めません。

operationIdは任意です。ツールやチームがoperationを安定して識別するために使う場合だけ記録します。記録するなら、API内で一意にし、大文字と小文字を区別します。変更規則と責任者も決めます。

入力をparametersとrequestBodyに分ける

入力は、HTTPメッセージのどこを通るかでParameter ObjectとRequest Body Objectへ分けます。通常のParameter Objectはpath、query、header、cookieの個別値を扱います。直列化とは、値をURL、header、cookieなどで送れる表現へ変換する規則です。OAS 3.2.0には、URLのquery string全体を一つの値として扱うquerystringもあります。Parameter Objectの規範で区分と条件を確認できます。

in: querystringは通常のqueryと同じ扱いではありません。Parameter Objectのnameは必須ですが、直列化には使いません。requiredを省略するとfalseです。特定のoperationに適用されるPath ItemとOperationのparametersを合わせて最大一つだけ置けて、どちらの階層でもin: queryとは併用できません。値の記述にはcontentが必須で、schemaは使えません。この条件と採用ツールの対応を確認できない場合は、querystringを選ばずHOLDにします。

requiredは三つの階層で分ける

入力 使う場所 必須性を決める場所 HOLDにする状態
通常のParameter path、query、header、cookie Parameter Objectのrequired 運ばれ方や直列化方法を決められない
querystring Parameter URLのquery string全体 contentを使うParameter Objectのrequired queryとの排他やツール対応を確認できない
Request body リクエストの内容を送る処理 Request Body Objectのrequired bodyを送る意味やmedia typeを決められない
body内のproperty request bodyのSchema JSON Schemaのrequired 欠落、null、空値の意味が未決定

path parameterはrequired: trueが必要です。それ以外のparameterは、requiredを省略するとfalseです。request body自体も省略時はfalseになります。通常のParameter Objectは、値の記述にschemaかcontentのどちらか一方を使います。Request Body Objectではcontentが必須です。

requiredとnullは別の判断です。JSON Schemaのobject解説では、requiredはpropertyの存在を求めます。propertyがない状態と、存在して値がnullである状態は同じではありません。JSON Schemaのnull解説もこの差を示しています。nullを許すなら、使用するdialectに従って許容typeへnullを含めます。

media typeとSchemaで入出力を制約する

media typeは送受信内容の形式、Schemaはデータの構造と制約を表します。OASのMedia Type Objectは、requestとresponse、parameterとheaderの内容全体をSchemaで記述できます。OAS 3.2.0のMedia Type Objectを基準にします。

Schemaへ書くのはproperty名とtypeだけではありません。必須性と許容値、長さや範囲、組み合わせを記録します。欠落とnullの意味、業務上変えてはいけない条件も記録します。データ構造の正本や関係が不明なら、先にER図とデータモデルを確認します。

OAS 3.2.0のSchema Objectは、JSON Schema Draft 2020-12 ValidationとJSON Schema Coreを基礎にします。ただし、formatは既定では注釈として扱われ、入力を拒否するかは実装や設定で異なります。制約を書いた後、validator（Schemaに照らしてデータを検査するツール）が不正な入力を拒否することを別に確かめます。

exampleは任意の補助資料です。置く場合はSchema、media type、encodingに合うか確認しますが、一件のexampleは他の入力や実装の正しさを証明しません。ここでは完成済みの架空exampleを置かず、必要な根拠への参照欄だけを作ります。

成功時とエラー時のresponseを決める

responseは、status code、結果の意味、media type、Schemaを対応づけます。OAS 3.2.0のResponses Objectは少なくとも一つのresponse codeを必要とし、成功時と既知のエラー時のresponseを記述することを期待しています。Responses Objectの規範を確認できます。

status codeは数字の慣例だけで選びません。RFC 9110のStatus Codesに照らし、HTTPメソッド、業務結果、返却内容の意味が一致するcodeを選びます。すべてのAPIに共通する固定の成功code・エラーcodeはありません。既知の結果を個別に書き、列挙していないresponseの扱いも決めます。

本記事では、個人情報または個人データとして管理する可能性があるものを「プライバシー対象データ」と呼びます。個別の区分は記事内で決めず、承認済みの分類基準と専門担当者で確認します。

機械処理しやすい共通エラー形式が必要なら、RFC 9457のProblem Detailsとapplication/problem+jsonを選択肢にできます。必須形式ではなく、既存の業務固有形式が適する場合もあります。Problem Detailsは実装時のデバッグ情報を返す形式ではありません。スタックトレース、内部構成、秘密情報、プライバシー対象データを含めず、公開範囲をセキュリティ担当者が確認します。

componentsとreferenceは共有時だけ使う

本記事では、同じSchemaやresponseを複数のoperationで共有するときにComponents Objectへ置き、Reference Objectで参照します。これは最小契約に絞るための編集方針です。OAS上は、一度しか参照しないObjectを置くことも禁止していません。Components Object内の定義は、明示的に参照されるまでAPI定義では使用されません。Components ObjectとReference Objectで参照先とObject typeを確認します。

Reference Objectの$refはURIです。summaryとdescription以外のpropertyを同じReference Objectに追加しても適用されません。変更したい制約は参照先またはSchema Object側で扱います。共有すると変更の影響先も増えるため、責任者とレビュー対象を説明できなければ、一つ目のoperationでは直接記述する選択肢があります。

security requirementは認証設計への参照にする

security requirementは、operationに必要なSecurity Schemeへの契約上の参照です。scheme名またはSecurity Scheme Object URIで接続します。OASでは、URIに見えるcomponent名は非推奨です。Tsuzuraでは参照解決の曖昧さを避けるため使用しません。複数文書を参照する場合は、解決の起点、参照先、管理責任者、採用ツールでの解決結果を固定します。OAS 3.2.0のSecurity RequirementとSecurity Considerationsが、名前とURIの解決に曖昧さがあり得ると説明しています。

宣言があっても、認証・認可の設計、実装、権限確認が済んだことにはなりません。方式、役割、スコープ、対象リソース単位の許可が未承認なら、認証と認可の判断表へ戻してHOLDにします。

データの扱いをoperation全体で確認する

次はOASの規範要件ではなく、Tsuzuraの作業方針です。request bodyだけでなく、path・query・header・cookieのparameter、成功時とエラー時のresponse body、response headerを含むoperation全体を確認します。プライバシー対象データや秘密情報に該当する可能性、利用目的、プライバシー担当者、許可する受領者と利用者・システムを記録します。第三者または海外への移転、保持・削除条件は、該当する場合だけ承認済みのプライバシー要件と専門担当者のレビュー記録へ結び付けます。適用の有無を判断できない場合もHOLDです。

送受信するデータは、承認済み要件に必要な範囲に絞ります。URL、ログ、キャッシュに残る範囲と、記録時の削除・保護条件を確認します。権限のない利用者が別のリソースや別のテナント（同じサービス内でデータと権限を分ける利用者・組織の単位）の情報を読み書きできないこともテストします。分類、最小化、記録条件、権限外テストのどれかが未決ならHOLDにします。

ツールに渡す文書と参照先を制限する

OpenAPI文書は、検証、表示、テスト、コード生成など複数のツールへ渡ります。OAS 3.2.0は、外部リソースが自動取得される場合、参照の循環がリソース枯渇を起こす場合、MarkdownにHTMLやスクリプトが含まれる場合をSecurity Considerationsで挙げています。

次はOASの規範要件そのものではなく、Tsuzuraが採用するツール処理基準です。信頼できる管理元と固定版が分かる文書だけを処理します。外部URI、ファイル、ネットワークへのアクセスは既定で許可せず、必要な接続先だけを許可リストに入れます。参照の循環と処理量の上限を設定し、MarkdownはHTMLやスクリプトを無害化できるツールで表示します。生成物は隔離した環境で作り、人が差分を確認するまで実行や配備をしません。これらの制御を採用ツールで確認できなければHOLDです。

検証結果と人の採否を分ける

検証は一回の「valid」で終わりません。次の表はOASの規範フィールドではなく、Tsuzuraが実装前レビューに使う編集上の整理です。契約テストと人のレビューの行も、OASが要求する項目ではなく、本記事で採用する受入管理です。

検査 確認できること 単独では証明しないこと
OAS構造の検証 文書のフィールドとObjectを検査Schemaが扱える 規範違反がないこと、ツール間で同じ解釈になること
Schemaの検証 固定したvalidator・版・設定が、検査対象のデータを受理または拒否した 要件の網羅、別設定の結果、実装が同じ検証をすること
採用ツールの読み込み・表示・生成 固定版のツールが対象文書を処理できた 別のツールや版でも同じ結果になること、安全に実行できること
契約テスト 固定した実装版が、選んだリクエスト・レスポンス条件に合う 未テスト条件、認可、未知のエラー、業務受入、AI出力の品質
人のレビュー 責任者が根拠、未知事項、互換性懸念を見て採否を決めた 将来も変更なしで安全に使えること

OpenAPI Initiativeが公開するJSON Schemaは参考資料です。OAS 3.2.0は、Schemaと規範本文が一致しない場合に本文を優先すると定めています。公式のSpecification indexも、Schemaが全仕様違反を検出する保証はないと説明します。最終採否はツールではなく、承認権限を持つ人が固定版に対して決めます。

AIへ任せる範囲を一つのoperationに限る

AIに下書きを任せる場合は、承認済みの要件・受入条件と、一つのoperationだけを渡します。空欄を推測で埋めること、HTTPメソッドやstatus code、security requirementを根拠なく選ぶこと、参照先を差し替えることは認めません。人が入力と出力の差分、参照先の版、検証結果を確認します。AI採用の妥当性や出力品質の評価、本番運用はこの契約レビューでは証明できません。

空欄のOpenAPI作成票

次の票は、Tsuzuraが一つのoperationを実装前にレビューするための編集用テンプレートです。OASが要求する規範フィールドの一覧でも、完成したOpenAPI Documentの例でもありません。

承認と責任者、版とoperation、入力と出力、security requirement、検証と互換性、未決事項とHOLD条件の順に埋めます。値が未決なら、推測せず「未決」と書き、責任者と再判断条件を残します。使わない項目は「該当なし」とし、使わない理由を残します。

# OpenAPI作成票

## 対象と承認
- operationの目的:
- 利用者・呼び出し元:
- 影響を受ける利用者・システム:
- 要件の参照先と承認版:
- 受入条件の参照先と承認版:
- 契約の責任者:
- レビュー担当者:
- 最終採否を決める人:
- レビュー日:
- 各役割の兼任と組織の承認ルール:
- 独立確認が必要になる条件と担当者:
- AIへ渡した承認済み資料（使わない場合は「不使用」）:
- AIに推測させない項目:
- 人が確認した差分:
- AI機能の評価資料・責任者・承認状態（該当しない場合は「該当なし」と理由）:

## 仕様とツールの版
- OpenAPI Specification version:
- OpenAPI Document version (`info.version`):
- APIまたはOpenAPI Description全体の版（別に持つ場合）:
- Schema dialect URI:
- 使用するJSON Schemaのキーワードとvocabulary（語彙）:
- 作成ツール名・版・対応範囲の根拠:
- 利用ツール名・版・対応範囲の根拠:
- ソースの管理場所と固定版:

## Operation
- relative path:
- HTTP method:
- methodを選んだ根拠:
- operationId（使わない場合は理由）:
- 開始条件:
- 成功条件:
- 外部への作用:
- 今回変えない範囲:

## データとプライバシー
- operation全体で扱うプライバシー対象データ・秘密情報の分類:
- 承認済みプライバシー要件の参照先:
- 対象となるデータ項目と利用目的:
- プライバシーの責任者・レビュー担当者:
- 許可する受領者・利用者・システム:
- 第三者または海外への移転の有無と承認記録:
- 保持・削除条件:
- データの最小化と、URL・ログ・キャッシュの記録・保護条件:
- 権限のない利用者による別リソース・別テナントへの読み書きを拒否するテスト:
- 専門担当者のレビューが必要になる条件と記録:

## 入力（個別のparameter）

| 名前 | `in`（path・query・header・cookie） | `required` | `schema`または`content` | 直列化方法 | データ分類・記録条件 | 制約・不変条件 | 根拠 | 未決事項 |
|---|---|---|---|---|---|---|---|---|
|  |  |  |  |  |  |  |  |  |

## Query string全体（`in: querystring`を使う場合だけ）
- 使用理由:
- name（直列化には使わないがParameter Objectでは必須）:
- required（省略時false）:
- Path ItemとOperationのどちらにも`in: query`がないこと:
- Path ItemとOperationを合わせ、同じoperationへ適用される`querystring`が一つだけであること:
- `content`のmedia typeとSchema:
- 直列化方法:
- URL・ログ・キャッシュの記録・保護条件:
- 作成側・利用側ツールの対応確認:

## Request body
- bodyの有無と理由:
- required:
- media type:
- Schemaまたは参照先:
- required property:
- optional property:
- nullを許すpropertyと理由:
- 制約・不変条件:
- request exampleの要否と根拠の参照先:
- operation全体のデータ分類との対応、request body固有の送信条件:
- 本番token、API key、cookie、実在するプライバシー対象データを記載していないこと:

## 出力

| status code | 結果の意味 | media type | Schemaまたは参照先 | header | データ分類・公開条件 | エラーの識別子・構造 | 根拠 | 未決事項 |
|---|---|---|---|---|---|---|---|---|
|  |  |  |  |  |  |  |  |  |

## Security requirement
- security requirement:
- 参照するSecurity Scheme:
- URIに見えるcomponent名を使っていないこと:
- 参照解決の起点・参照先・管理責任者:
- 匿名アクセスの有無:
- 認証・認可設計の承認記録:
- operation固有の役割・権限範囲・対象リソースの条件:
- 別リソース・別テナントへの権限外アクセスを拒否するテスト:
- セキュリティのレビュー担当者:

## 参照先とツールで信頼して扱う範囲
- 文書と外部参照の管理元・固定版:
- 許可する外部URI・ファイル・ネットワークアクセス:
- 参照の循環と処理量の上限:
- MarkdownのHTML・スクリプト無害化結果:
- 生成物を隔離した場所と人による差分確認:

## 再利用・互換性・戻し方
- componentsへ置くObjectと理由:
- `$ref`の参照元・参照先:
- 変更時の影響先:
- 既存利用者への互換性懸念:
- 変更前の契約ソースと固定版:
- 契約変更を戻す判断条件:
- 戻す対象・担当者・手順の参照先:
- 戻した後に行う検証:
- 稼働中システムの切り戻しは別成果物で管理していること:

## 未決事項と根拠
- 未決事項:
- 各未決事項の責任者:
- 要件・ADR・テスト・公式資料などの根拠:
- exampleを使う場合のソースと検証結果（合成データだけを使う）:
- 仕様の変更契機:
- 要件・Schema・セキュリティ要件の変更契機:
- ツール・フレームワークの変更契機:
- 次回レビュー条件:

## 検証と採否
- OAS構造検証のツール・版・設定・結果:
- Schema検証のdialect・ツール・版・設定・検査対象・結果:
- 不正入力を使った検証の結果:
- 作成側と利用側ツールの読み込み・表示・生成結果:
- 契約テストの対象実装版・対象条件・結果:
- 未テスト・未確認の範囲:
- 最終判断（GO・HOLD・DROP）:
- 判断理由と受け入れるリスク:
- 判断者と日時:

## HOLD条件
- 現在HOLDに該当する条件:
- 足りない情報・承認・検証:
- 解消する責任者:
- 再判断する条件:

HOLDにする条件

次はTsuzuraの編集上のHOLD基準であり、OASの規範要件ではありません。どれかを説明できない場合は、実装へ渡さず、誰が何を決めれば再開できるかを残します。

  • 要件または受入条件が未承認で、operationの成功を決められない
  • 利用者、契約の責任者、最終採否を決める人が不明
  • 役割の兼任が組織ルールに合うか不明、または必要な独立確認の担当者がいない
  • path、HTTPメソッド、入力の運ばれ方、外部への作用が決まらない
  • required、欠落、null、空値の扱いが未決
  • 成功時または既知エラー時のstatus、media type、Schemaが決まらない
  • security requirementや認可条件が未承認、またはエラー情報の公開範囲が不明
  • operation全体のデータ分類、利用目的、受領者・利用者・システム、保持・削除条件のどれかが未決
  • 第三者・海外移転への該当性が不明、または必要なプライバシー責任者・専門担当者のレビュー記録がない
  • parameter、response body・header、URL・ログ・キャッシュの最小化・保護条件、権限外テストのどれかが未決
  • 作成側と利用側のツールが、固定したOAS versionとSchema dialectを必要な範囲で扱えると確認できない
  • 文書、外部参照、Markdown表示、生成物の信頼できる範囲を確認できない
  • 既存利用者への互換性懸念や契約変更を戻す条件に責任者と記録がない
  • 検証結果が対象ソース版、ツール版、設定、検査対象、実装版へ結び付かない

空欄を推測で埋めたり、exampleを合意の代わりにしたりせず、担当者へ戻します。

次の工程へ渡す

作成票がGOになったら、一つのoperationをAIに渡す実装タスクへ切り出し、Schema検証と契約テストをテストの種類と選び方へ追加します。ツールやフレームワークをまだ選んでいない場合は、必要なOAS版、dialect、検証機能を技術選定の条件へ渡します。

GOでも、実装と認証・認可、業務受入、運用は完了していません。性能と可用性、遅延、費用は非機能要件で扱います。利用上限と監視、秘密情報の管理、バックアップ・復元は、Webサービスの最低限の運用設計へ渡します。AI機能なら、採用理由と評価データ、品質指標と許容誤差を別に承認します。代替動作と人への切り替え条件も別に承認します。評価資料の参照先と責任者、承認状態は作成票に戻します。

実装後は、停止、切り戻し、責任者への引き上げの条件を含む公開判断をサービス公開前の確認で行います。同じ契約版とテストの根拠を使い、実装時点で変わった項目があれば作成票へ戻します。

出典