OpenAPIインターフェース仕様
OpenAPI は、HTTP API を記述する標準的な方法です。今日はそのインターフェース仕様( OpenAPI仕様(中国語版) )についてお話しましょう~
OpenAPI バージョン番号の仕様
OpenAPI のバージョン番号は、3.1.2 などの Major.minor.patch の形式を使用して定義されます。
- Major: メジャー バージョンを指定します
- マイナー: マイナー バージョンを指定します
- patch: マイナーバージョンのパッチを指定します。
OpenAPIフォーマット仕様
OpenAPI はJSONまたは YAML 形式を使用でき 、フィールドでは大文字と小文字が区別されます。
JSONの例
YAML の例
OpenAPI ドキュメント構造仕様
OpenAPI ドキュメントは、チームの裁量により、単一のドキュメントまたは複数のドキュメントにすることができます。後者の場合、$ref キーワードを参照オブジェクトとスキーマ オブジェクトで使用する必要があります。
ドキュメントの名前については、 openapi.json
または という名前を推奨しますopenapi.yaml
。
OpenAPI データ型の仕様
OpenAPIのデータ型 は、JSON Schema仕様ドラフト2020-12の仕様に準拠する必要があります。
JSON スキーマ仕様アドレス: draft-bhutton-json-schema-00
OpenAPI リッチ テキスト形式の仕様
OpenAPI の説明フィールドは CommonMark マークダウン形式をサポートしているため、OpenAPI でリッチ テキストを使用する場合、形式は CommonMark マークダウン形式に準拠する必要があります。
OpenAPI オブジェクト
情報オブジェクト
APIを説明するメタデータ
接触オブジェクト
APIの連絡先情報
サーバーオブジェクト
APIサーバーオブジェクト情報
サーバーになれる
複数のサーバーにすることもできます
コンポーネントオブジェクト
API の再利用可能なコンポーネント オブジェクト
パスオブジェクト
APIのURLを記述するオブジェクト
パス項目オブジェクト
単一のパスで操作が可能なオブジェクト
操作オブジェクト
パス上の単一の API オペレーションのオブジェクト
外部ドキュメントオブジェクト
外部リソースを拡大する
パラメータオブジェクト
パラメータオブジェクト
リクエストボディオブジェクト
単一のリクエストボディのオブジェクト
応答オブジェクト
API は応答オブジェクトを返します
ヘッダーオブジェクト
リクエストヘッダーオブジェクト
知識の拡大: