OpenAPI

OpenAPI Specification

swagger.io でできたりしたもの

OpenAPI仕様とは？

OpenAPI仕様（OAS）は、HTTP APIの標準的なプログラミング言語に依存しないインターフェース記述を定義します。これにより、人間とコンピューターの両方が、ソースコードや追加ドキュメントへのアクセス、ネットワークトラフィックの検査を必要とせずに、サービスの機能を発見し理解できるようになります。OpenAPIを介して適切に定義されていれば、利用者は最小限の実装ロジックでリモートサービスを理解し、操作できます。インターフェース記述が低レベルプログラミングにもたらしたものと同様に、OpenAPI仕様はサービス呼び出しにおける推測を排除します。

このドキュメントのステータス

この仕様の信頼できる情報源は、上記で「このバージョン」として参照されているHTMLファイルです。

1. OpenAPI 仕様

1.1 バージョン 3.2.0

本文書は、Apache License バージョン 2.0 に基づいてライセンスされます。

2. はじめに

OpenAPI 仕様 (OAS) は、HTTP API への標準的かつ言語に依存しないインターフェースを定義します。これにより、人間とコンピューターの両方が、ソースコードやドキュメントにアクセスしたり、ネットワークトラフィックを検査したりすることなく、サービスの機能を発見し、理解することができます。適切に定義されている場合、コンシューマーは、最小限の実装ロジックでデータモデルとの間で HTTP メッセージを解析およびシリアル化することで、リモートサービスを理解し、対話することができます。

OpenAPI 記述 (OAD) は、API を表示するためのドキュメント生成ツール、様々なプログラミング言語でサーバーとクライアントを生成するためのコード生成ツール、テストツールなど、様々なユースケースで使用できます。

2.1 バージョンと非推奨

OpenAPI 仕様は、major.minor.patch というバージョン管理方式を用いてバージョン管理されます。バージョン文字列の major.minor 部分（例：3.1）は、OAS 機能セットを指定するものとします。.patch バージョンは、機能セットではなく、このドキュメント内のエラーを修正したり、説明を提供したりするためのものです。OAS 3.1 をサポートするツールは、すべての OAS 3.1.* バージョンと互換性を持つべきです。ツールはパッチバージョンを考慮に入れるべきではなく、例えば 3.1.0 と 3.1.1 を区別しません。

一部のフィールドまたは機能は「非推奨」とマークされている場合があります。これらのフィールドと機能は仕様の一部として残り、他のフィールドや機能と同様に使用できます。ただし、OpenAPI 記述の作成者は、可能な限り、非推奨のフィールドと機能を、ドキュメントに記載されている新しいフィールドと機能に置き換える必要があります。

現時点では、これらの要素は次期メジャーバージョンまで OAS の一部として残ることが想定されていますが、本仕様の将来のマイナーバージョンでは、非推奨の要素を後日削除するためのポリシーが定義される可能性があります。

場合によっては、OAS のマイナーバージョンにおいて、提供される利点に比べて影響度が低いと考えられる場合、後方互換性のない変更が行われることがあります。

2.2 未定義の動作と実装定義の動作

本仕様では、特定の状況において、未定義の動作または実装定義の動作が発生するものとみなします。

未定義と記述された動作は、少なくとも一部の状況において、仕様と矛盾する結果をもたらす可能性があります。この記述は、矛盾の検出が不可能または非現実的な場合に使用されます。実装は、過去の仕様における曖昧なテキストなど、歴史的な理由により、未定義のシナリオをサポートしてもよいものとします。このサポートは多くの場合正しい結果をもたらす可能性がありますが、このサポートに依存することは推奨されません。なぜなら、たとえそれらのバージョンがこの仕様と厳密に互換性があっても、すべてのツールや将来の仕様バージョンで動作することが保証されないからです。

実装定義として記述された動作により、実装は要件に対する複数の異なるが準拠したアプローチの中から、どのアプローチを実装するかを選択できます。これは、API記述の作成者が相互運用性を最大限に高めるために避けることが推奨される、曖昧な要件を文書化したものです。未定義の動作とは異なり、関連するすべてのツールが同じ動作をサポートしていることが保証される場合にのみ、実装定義の動作に依存できます。

3. フォーマット

OpenAPI 仕様に準拠する OpenAPI ドキュメント自体は JSON オブジェクトであり、JSON 形式または YAML 形式で表現できます。この仕様では、簡潔にするために例を YAML で示します。

仕様内のすべてのフィールド名は大文字と小文字が区別されます。これは、マップのキーとして使用されるすべてのフィールドに適用されます。ただし、キーの大文字と小文字が区別されないことが明示的に示されている場合は除きます。

OAS オブジェクトは、宣言された名前を持つ固定フィールドと、宣言されたパターンを持つパターン化フィールドの 2 種類のフィールドを公開します。

パターン化フィールドは、包含オブジェクト内で一意の名前を持つ必要があります。

注: API は YAML または JSON 形式の OpenAPI 記述で記述できますが、API リクエストとレスポンスの本文、およびその他のコンテンツは、必ずしも JSON または YAML である必要はありません。

3.1 JSON と YAML の互換性

本仕様の以前のバージョンでは、YAML を「JSON」スキーマルールセットに制限するという推奨事項がありましたが、これにより、名前に反して JSON では表現できない特定の値を含めることが可能になりました。OAD の作成者は、このような JSON と互換性のない YAML 値を使用すべきではありません。

3.2 大文字と小文字の区別

OpenAPI 仕様のほとんどのフィールド名と値は大文字と小文字が区別されるため、本ドキュメントでは大文字と小文字を区別しない名前と値についても明確に記載するよう努めています。ただし、HTTP の概念に直接対応するフィールド名と値の大文字と小文字の区別は、本ドキュメントですべての概念について言及しているわけではありませんが、HTTP の大文字と小文字の区別ルールに従います。

3.3 リッチテキストフォーマット

CommonMark 0.27 を最低要件と定めているため、ツールは CommonMark 0.27 をベースに拡張機能を実装することもできますが、そのような拡張機能は定義上実装定義であり、相互運用性がないことに注意してください。OpenAPI 記述の作成者は、そのような拡張機能を使用したテキストが、最低限のサポートしか提供していないツールによってどのようにレンダリングされるかを考慮する必要があります。

4. オブジェクトとフィールド

以下の説明において、明示的に「必須（REQUIRED）」と記載されていないフィールド、または「必須（MUST）」または「すべき（SHALL）」と記載されていないフィールドは、「任意（OPTIONAL）」とみなされます。

4.1 OpenAPIオブジェクト

これはOpenAPI記述のルートオブジェクトです。

4.1.1 固定フィールド

必須フィールドに加えて、コンポーネント、パス、またはWebhooksフィールドのうち少なくとも1つが必須です。

table:a

Field名 型 説明

openapi string 必須。この文字列は、OpenAPIドキュメントが使用するOpenAPI仕様のバージョン番号で

なければなりません。ツールは、openapiフィールドをOpenAPIドキュメントの解釈に使

用する必要があります。これは、OpenAPIドキュメントのバージョンを示すinfo.version

文字列とは関係ありません。

なりません。$self フィールドは、このドキュメントの自己割り当て URI を提供し、この

このフィールドが存在する場合、このフィールドで定義された URI を使用して API 記述

URI のターゲットを識別できるようにする必要があります。$self が存在しない場合、ま

たは相対パスである場合のベース URI の動作については、「ベース URI の確立」を参照

してください。また、$self を使用して参照を解決する例については、付録 F を参照して

ください。

info Info Object 必須。APIに関するメタデータを提供します。メタデータは必要に応じてツールによって

使用される場合があります。

jsonSchemaDialect string このOASドキュメントに含まれるスキーマオブジェクト内の$schemaキーワードのデフォ

ルト値。URI形式でなければなりません。

servers Server Object 対象サーバーへの接続情報を提供するサーバーオブジェクトの配列。servers フィールド

が指定されていない場合、または空の配列の場合、デフォルト値は、url 値が / である単

一のサーバーオブジェクトで構成される配列になります。

paths Paths Object API で使用可能なパスと操作。

webhooks Map[string, このAPIの一部として受信される可能性があり、APIコンシューマーが実装を選択できる着

Path Item 信 Webhookです。コールバック機能と密接に関連するこのセクションでは、API呼び出し

Object] 以外（例えば、帯域外登録など）によって開始されるリクエストについて説明します。

キー名は各Webhookを参照するための一意の文字列であり、（オプションで参照される）

パスアイテムオブジェクトは、APIプロバイダーによって開始される可能性のあるリクエス

トと、期待されるレスポンスを表します。例をご覧ください。

components Components OpenAPI 記述のさまざまなオブジェクトを保持する要素。

Object

security Security API全体で使用可能なセキュリティメカニズムの宣言です。値のリストには、使用可能な代

Requirement 替セキュリティ要件オブジェクトが含まれています。リクエストを承認するには、セキュ

Object リティ要件オブジェクトのいずれか1つを満たす必要があります。個々の操作でこの定義を

上書きできます。リストは不完全であってもよく、空または存在しない場合もあります。

セキュリティを明示的にオプションにするには、配列に空のセキュリティ要件 ({}) を含め

ることができます。

tags Tag Object OpenAPI記述で使用されるタグのリスト（追加メタデータ付き）。タグの順序は、解析ツ

ールによってタグの順序に反映されます。操作オブジェクトで使用されるすべてのタグを

宣言する必要はありません。宣言されていないタグは、ランダムに、またはツールのロジ

ックに基づいて配置できます。リスト内の各タグ名は一意である必要があります。

externalDocs External 追加の外部ドキュメント。

Documentation

Object

このオブジェクトは、仕様拡張によって拡張される場合があります。

相互運用性を確保するため、$self フィールドが存在する場合、参照では対象ドキュメントの $self URI を使用する必要があります。実装では、$self が存在する場合でも、取得 URI などの他の URI による参照をサポートすることもできますが、この動作は相互運用性がなく、これに依存することは推奨されません。

4.1.2 OpenAPI 記述の構造

OpenAPI 記述 (OAD) は、API の表面とそのセマンティクスを形式的に記述します。OAD は単一のドキュメントで構成される場合もあれば、URI 参照や暗黙的な接続を使用して様々なフィールドで接続された複数のドキュメントに分散されている場合もあります。

解析動作を明確に定義するために、OAD 内のすべてのドキュメントは、ルートに OpenAPI オブジェクトまたはスキーマオブジェクトのいずれかを持ち、次のセクションで説明するように完全なドキュメントとして解析される必要があります。

ルートに異なるオブジェクトを持つドキュメント、またはOADコンテンツと他のコンテンツが混在するドキュメントはサポートされてもよい（MAY）が、付録G「解析および解決ガイダンス」に記載されているように、実装定義の動作、または潜在的に未定義の動作となる可能性がある。本仕様では、特に指定がない限り、ドキュメントはルートにOpenAPIオブジェクトまたはスキーマオブジェクトのいずれかを持つものと想定される。

複数ドキュメントのOADでは、解析が開始されるOpenAPIオブジェクトを含むドキュメントを、そのOADのエントリドキュメントと呼ぶ。OADのエントリドキュメントの名前は、openapi.jsonまたはopenapi.yamlにすることが推奨される。

JSONスキーマがスキーマオブジェクトの形式でOASに埋め込まれるのと同様に、OpenAPIオブジェクトは埋め込み形式と呼ばれる別の形式で埋め込まれてもよい（MAY）が、埋め込みコンテンツの解析方法を定義するのは埋め込み形式の責任であり、埋め込み形式のサポートを文書化していないOAS実装では、埋め込まれたOASコンテンツを正しく解析することは期待できない。

4.1.2.1 文書の解析

OAD 内の各文書は、参照可能な対象を特定するために完全に解析されなければなりません（MUST）。これには、JSON Schema Specific Draft 2020-12 の解析要件が含まれますが、「URI における相対参照」で規定されているベース URI に関する適切な修正も含まれています。参照対象は、OpenAPI オブジェクトの $self フィールドや、スキーマオブジェクトの $id、$anchor、$dynamicAnchor キーワードなどのフィールドによって定義されます。

実装は、OAD の構成要素として実装に提供されたすべての文書を完全に解析する前に、参照を解決不可能なものとして扱ってはなりません（MUST NOT）。

参照を解決する際に文書の参照先部分のみを解析する場合、結果の動作は実装定義または未定義になる可能性があります。詳細については、付録 G の「断片的解析に関する警告」を参照してください。

4.1.2.2 API記述URIにおける相対参照

OpenAPI記述内、または外部ドキュメントやライセンスなどの補足情報への参照として使用されるURIは識別子として解決され、本仕様ではAPI URLとは対照的にURIとして記述されます。一部のURIフィールドは歴史的な理由からurlという名前が付けられていますが、それらのフィールドの説明文では正しい「URI」という用語が使用されていることに注意してください。

「ドキュメントの解析」で述べたように、OpenAPIドキュメントまたはスキーマオブジェクトをURIに関連付けるために使用できるフィールドがいくつかあります。これらのURIは、ドキュメントまたはスキーマの場所と一致しない場合があります。これにより、ローカルファイルシステムや、セキュリティポリシーや接続制限によって制限されているネットワークなど、異なるデプロイメント環境で同じ参照を使用できます。

4.1.2.2.1 ベースURIの確立

$self（OpenAPIオブジェクトの場合）および$id（スキーマオブジェクトの場合）が欠落している場合、または相対的な場合に使用される最も一般的なベースURIソースは、取得URIです。実装はドキュメント取得をサポートしてもよいですが（MAY）、追加のガイダンスについては「セキュリティに関する考慮事項」セクションを参照してください。検索がサポートされている場合でも、ネットワーク構成やサーバーが利用できない状況（新バージョンの開発中にサーバーが旧バージョンをホストしている場合を含む）により検索が不可能になる場合や、パフォーマンスへの影響により検索が望ましくない場合があります。したがって、すべての実装では、ユーザーが文書に意図する検索URIを提供できるようにし、検索が行われたかのように参照を解決できるようにする必要があります（SHOULD）。

4.1.2.2.2 URIフラグメントの解決

4.1.2.2.3 CommonMarkフィールドにおける相対URI参照

CommonMarkハイパーリンク内の相対参照は、レンダリングされたコンテキストで解決されます。これは、API記述のコンテキストとは異なる場合があります。

4.1.2.3 暗黙的な接続の解決

本仕様のいくつかの機能は、OpenAPI記述（OAD）の他の部分へのURIベースではない接続の解決を必要とします。

これらの接続は、単一文書のOADでは明確に解決されますが、複数文書のOADにおける解決プロセスは、本セクションで説明する制約の範囲内で実装定義となります。場合によっては、明確なURIベースの代替手段が利用可能であり、OAD作成者は相互運用性を最大限に高めるために、その代替手段を使用することが推奨されます。

参照先（エントリではない）文書からコンポーネントオブジェクトおよびタグオブジェクト名を解決する場合、ツールは現在の文書ではなくエントリ文書から解決することが推奨されます。operationIdに基づいて操作オブジェクトを解決する場合、解析対象のすべての文書のすべての操作オブジェクトを考慮することが推奨されます。

暗黙的な接続解決のいかなる側面も、URIの解決方法を変更したり、URIの可能なターゲットを制限したりしないことに注意してください。

暗黙的な接続を使用するオブジェクトとフィールドのリストを含む詳細については、「付録 G: 解析と解決のガイダンス」を参照してください。

4.2 情報オブジェクト

このオブジェクトは、APIに関するメタデータを提供します。このメタデータは、必要に応じてクライアントが使用してもよいほか、編集ツールやドキュメント生成ツールで利便性のために提示してもよいものとします。

4.2.1 固定フィールド

table:a

Field名 型 説明

title string 必須。API のタイトル。

summary string API の簡単な概要。

termsOfService string APIの利用規約のURI。URI形式でなければなりません。

contact Contact Object 公開された API の連絡先情報。

license License Object 公開された API のライセンス情報。

version string 必須。OpenAPI ドキュメントのバージョン（OpenAPI 仕様のバージョン、記述されている

API のバージョン、または OpenAPI 記述のバージョンとは異なります）。

このオブジェクトは仕様拡張によって拡張される場合があります。

4.2.2 Info Object の例

code:Info Object.yaml

title: Example Pet Store App

summary: A pet store manager.

description: This is an example server for a pet store.

contact:

name: API Support

email: support@example.com

license:

name: Apache 2.0

version: 1.0.1

4.3 連絡先オブジェクト

公開APIの連絡先情報。

4.3.1 固定フィールド

table:a

Field名 型 説明

name string 連絡先担当者/組織の識別名。

url string 連絡先情報のURI。URI形式でなければなりません。

email string 連絡先担当者/組織のメールアドレス。メールアドレスの形式で入力する必要があります。

このオブジェクトは仕様拡張によって拡張される場合があります。

4.3.2 連絡先オブジェクトの例

code:ContactObject.yaml

name: API Support

email: support@example.com

4.4 ライセンスオブジェクト

公開APIのライセンス情報。

4.4.1 固定フィールド

table:a

Field名 型 説明

name string 必須。API に使用されるライセンス名。

url string APIに使用されるライセンスのURI。URI形式でなければなりません。

urlフィールドはidentifierフィールドと相互に排他的です。

このオブジェクトは仕様拡張によって拡張される場合があります。

4.4.2 ライセンスオブジェクトの例

code:license.yaml

name: Apache 2.0

identifier: Apache-2.0

4.5 サーバーオブジェクト

サーバーを表すオブジェクト。

4.5.1 固定フィールド

table:a

Field名 型 説明

url string 必須。対象ホストへのURL。このURLはサーバー変数をサポートし、相対URLにすることができます。

相対URLは、サーバーオブジェクトを含むドキュメントが提供されている場所を基準としたホストの

位置を示します。クエリとフラグメントをこのURLに含めることはできません。変数名が{括弧}で囲

まれている場合は、変数の置換が行われます。

構文を使用できます。

name string URL によって指定されたホストを参照するためのオプションの一意の文字列。

variables Map[string, 変数名とその値のマッピング。この値は、サーバーのURLテンプレートにおける置換に使用されます。

Server Variable

Object]

このオブジェクトは、仕様拡張によって拡張される場合があります。

4.5.2 API URL における相対参照

API エンドポイントは定義上、場所としてアクセスされ、この仕様では URL として記述されます。

API は OpenAPI ドキュメントとは別のエンティティであるため、RFC3986 の OpenAPI ドキュメントに対するベース URI 規則は適用されません。特に指定がない限り、相対参照は、サーバーオブジェクトで定義されている URL をベース URL として使用して解決されます。これらの URL 自体は、参照元のドキュメントを基準としてもよいことに注意してください。

4.5.2.1 API ベース URL の決定例

code:baseurl.yaml

openapi: 3.2.0

info:

title: Example API

version: 1.0

servers:

- url: .

description: The production API on this device

- url: ./test

description: The test API on this device

4.5.3 サーバーオブジェクトの例

単一のサーバーは次のように記述されます。

code:server.yaml

description: Development server

name: dev

以下は、OpenAPI オブジェクトのサーバーなどの複数のサーバーを記述する方法を示しています。

code:servers.yaml

servers:

description: Development server

name: dev

description: Staging server

name: staging

description: Production server

name: prod

以下は、サーバー構成で変数を使用する方法を示しています。

code:servers.yaml

servers:

description: The production API server

name: prod

variables:

username:

# 注意！ここに列挙型がないということは、オープン値であることを意味します

default: demo

port:

enum:

- '8443'

- '443'

default: '8443'

basePath:

# オープンとは、プロバイダーによって割り当てられた特別なベースパスを使用する機会があることを意味します。デフォルトは「v2」です。

default: v2

4.6 サーバー変数オブジェクト

サーバーURLテンプレートの置換に使用するサーバー変数を表すオブジェクト。

code:serverurl.abnf

server-url-template = 1*( literals / server-variable )

server-variable = "{" server-variable-name "}"

server-variable-name = 1*( %x00-7A / %x7C / %x7E-10FFFF ) ; every Unicode character except { and }

literals = 1*( %x21 / %x23-24 / %x26-3B / %x3D / %x3F-5B

/ %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate

/ pct-encoded)

; any Unicode character except: CTL, SP,

; DQUOTE, "%" (aside from pct-encoded),

; "<", ">", "\", "^", "`", "{", "|", "}"

pct-encoded = "%" HEXDIG HEXDIG

ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF

/ %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD

/ %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD

/ %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD

/ %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD

/ %xD0000-DFFFD / %xE1000-EFFFD

iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD

各サーバー変数は、URLテンプレート内で複数回出現してはなりません（MUST）。

完全なリクエストURLの構築方法については、Pathsオブジェクトを参照してください。

4.6.1 固定フィールド

table:固定Field

Field名 型 説明

配列は空であってはなりません。

default string 必須。置換に使用するデフォルト値。代替値が指定されていない場合は、この値が送信されるもの

とします。列挙型が定義されている場合、その値は列挙型の値に存在しなければなりません。この

動作は、スキーマオブジェクトの default キーワードとは異なることに注意してください。default

キーワードは、データに値を挿入するのではなく、受信側の動作を記述します。

このオブジェクトは、仕様拡張によって拡張される場合があります。

4.7 コンポーネントオブジェクト

OAS の様々な側面に対応する再利用可能なオブジェクトのセットを保持します。コンポーネントオブジェクト内で定義されたすべてのオブジェクトは、コンポーネントオブジェクトの外部から明示的に参照されない限り、API に影響を与えません。

4.7.1 固定フィールド

table:a

Field名 型 説明

schemas Map[string, Schema 再利用可能なスキーマ オブジェクトを保持するオブジェクト。

Object]

responses Map[string, Response Object | Reference 再利用可能なレスポンス オブジェクトを保持するオブジェクト。

Object]

parameters Map[string, Parameter Object | Reference 再利用可能なパラメーター オブジェクトを保持するオブジェクト。

Object]

examples Map[string, Example Object | Reference 再利用可能なサンプルオブジェクトを保持するオブジェクト。

Object]

requestBodies Map[string, Request Body Object | 再利用可能なリクエスト ボディ オブジェクトを保持するオブジェクト。

Reference Object]

headers Map[string, Header Object | Refernece 再利用可能なヘッダー オブジェクトを保持するオブジェクト。

Object]

securitySchemes Map[string, Security Scheme Object | 再利用可能なセキュリティ スキーム オブジェクトを保持するオブジェクト。

Reference Object]

links Map[string, Link Object | Reference 再利用可能なリンク オブジェクトを保持するオブジェクト。

Object]

callbacks Map[string, Callback Object | Reference 再利用可能なコールバック オブジェクトを保持するオブジェクト。

Object]

mediaTypes Map[string, Media Type Object | 再利用可能なメディア タイプ オブジェクトを保持するオブジェクト。

Reference Object]

このオブジェクトは仕様拡張によって拡張される場合があります。

フィールド名の例：

code:Field Name

User

User_1

User_Name

user-name

my.org.User