略 : OAS

よく知られている REST API 記述フォーマット

プログラミング言語に依存しない

OpenAPI Initiative (OAI) が推進している

歴史

以前は Swagger Specification と呼ばれていた

2015 年 11 月に OAI に寄贈され、2016 年に 「OpenAPI Specification」 に改名

Swagger Specification 2.0 が OpenAPI Specification 2.0 に

その後もバージョン更新が行われている (https://github.com/OAI/OpenAPI-Specification/tree/main/versions 参照)

OAS を理解するために OpenAPI Map がおすすめ

記述には次のフォーマットを利用できる

文書記述には任意のテキストエディタを使用できる

OAS 対応の Swagger Editor というオンラインエディタがある

Visual Studio Code 用の拡張機能として 『Web API の設計』 では Swagger Viewerと openapi-lint が紹介

OAS を元に API リファレンスマニュアルを生成する方法

Swagger UI や Redoc

コードの自動生成にも利用できる

API ゲートウェイソリューションなども、OAS の API 記述ファイルで設定できる

クエリパラメータ、ボディパラメータ、レスポンスボディを含めて、すべてのデータを JSON Schema で表現

仕様の Shema Object の項目を参照 : https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject (v3.1.0 のリンク)

再利用可能なコンポーネントの定義

components で定義して $ref で参照

スキーマは components の中の schemas で

パラメータは parameters

参考文献