OpenAPI
OpenAPI Specification |
開始年 |
2010年 (2010) |
---|
初版 |
2011年8月10日 (2011-08-10) |
---|
最新版 |
3.1.0 2021年2月15日 (2021-02-15) |
---|
ウェブサイト |
openapis.org |
---|
OpenAPI Specification(以前はSwagger Specificationとして知られていた)は、Webサービスを記述、生成、消費、可視化するための機械可読なインターフェース記述言語の仕様である[1]。以前はSwaggerフレームワークの一部だったが、2015年に独立したプロジェクトとなり、Linux Foundationのオープンソース共同プロジェクトであるOpenAPI Initiativeが統括している[2]。
OpenAPIドキュメントはAPIの正式な記述であり、ツールがコード、ドキュメント、テストケースなどを生成するために使用できる。
歴史
Swaggerの開発は、オンライン辞書会社Wordnikに勤務していたトニー・タムによって2010年初めに開始された[3]。
2015年3月、SmartBear SoftwareはWordnikの親会社であるReverb TechnologiesからオープンソースのSwagger API仕様を買収した[4]。
2015年11月、SmartBearはLinux Foundationの後援のもと、OpenAPI Initiativeという新しい組織にSwagger仕様を寄贈すると発表した。他の創設メンバー企業には、3scale、Apigee、キャピタル・ワン、Google、IBM、インテュイット、マイクロソフト、PayPal、Restletが含まれる[5][6]。
2016年1月1日、Swagger仕様はOpenAPI Specification (OAS)と改名され、新しいGitHubリポジトリに移された[7]。
2017年7月、OpenAPI Initiativeは仕様のバージョン3.0.0をリリースした[8]。代替のRESTful API Modeling Language (RAML)の主要な貢献者であったMuleSoftは、OASに参加し、RAMLの入力からOASドキュメントを生成できるAPI Modeling Frameworkツールをオープンソース化した[9]。
2021年2月、OpenAPI Initiativeはバージョン3.1.0をリリースした[10]。OpenAPI Specification 3.1.0の主な変更点としては、JSONスキーマ語彙の調整、帯域外で登録・管理されるWebhookを記述するための新しいトップレベル要素、標準SPDX識別子を使用したAPIライセンスの識別のサポート、スキーマ参照の使用と並行した記述の許容、再利用可能なコンポーネントライブラリの作成を簡素化するためのPathItemsオブジェクトをオプションとする変更などがある[11][12][13]。
リリース日
バージョン
|
日付
|
説明[14]
|
3.1.0
|
2021年2月15日
|
OpenAPI Specification 3.1.0のリリース
|
3.0.3
|
2020年2月20日
|
OpenAPI Specification 3.0.3のパッチリリース
|
3.0.2
|
2018年10月8日
|
OpenAPI Specification 3.0.2のパッチリリース
|
3.0.1
|
2017年12月6日
|
OpenAPI Specification 3.0.1のパッチリリース
|
3.0.0
|
2017年7月26日
|
OpenAPI Specification 3.0.0のリリース
|
2.0
|
2014年9月8日
|
Swagger 2.0のリリース
|
1.2
|
2014年3月14日
|
正式ドキュメントの最初のリリース
|
1.1
|
2012年8月22日
|
Swagger 1.1のリリース
|
1.0
|
2011年8月10日
|
Swagger Specificationの最初のリリース
|
使用方法
OpenAPIインターフェースファイルに基づいて実装されたアプリケーションは、メソッド、パラメータ、データモデルのドキュメントを自動的に生成することができる。これにより、ドキュメント、クライアントライブラリ、ソースコードの同期を保つことができる[15]。
OpenAPIドキュメントを使用してサーバ用のソースコードスタブを生成する場合、そのプロセスはスキャフォールディング (scaffolding)と呼ばれる。
ソフトウェア工学のプラクティスとの関係
最初にプログラムをコーディングし、その後でその動作をコントラクトとして遡及的に記述するのとは対照的に、最初にAPIコントラクトに合意し、その後でビジネスロジックをプログラミングするというパラダイムは、コントラクト優先開発と呼ばれる。コードが書かれる前にインターフェースが決定されるため、下流の開発者はサーバの動作をモックし、すぐにテストを開始することができる[16]。この意味で、コントラクト優先開発は、シフトレフトテストの実践でもある。
機能
OpenAPI Specificationは言語に依存しない。OpenAPIの宣言的なリソース仕様により、クライアントはサーバの実装を知らなくても、サーバコードにアクセスしなくても、サービスを理解し利用することができる[15]。
OpenAPIを扱うツール
OpenAPI Initiativeは、仕様のバージョン3.0の実装リストを管理している。SmartBearは現在もOpenAPIツールにSwaggerのブランドを冠している。Swagger UIフレームワークを使用すると、開発者と非開発者の両方が、APIがパラメータやオプションにどのように反応するかを知ることができるサンドボックスUIでAPIと対話することができる。SwaggerはJSONとXMLの両方を扱うことができる[15]。
Swagger Codegenには、OpenAPI定義を解析することで、さまざまな言語のドキュメント、APIクライアント、サーバスタブを生成するテンプレート駆動エンジンが含まれている。2018年7月、Swagger Codegenの筆頭貢献者であるウィリアム・チェンと40人以上の他の貢献者が、OpenAPI Tools組織の下でOpenAPI Generatorというプロジェクトにコードをフォークした[17][18]。
年次会議
OpenAPI Initiativeは毎年API Specification Conference (ASC)を主催している。このイベントの起源は、長年運営され、2016年にOpenAPI Initiativeの一部となったAPI Strategy and Practice Conference (APIStrat)にある。
出典
参考文献
関連項目
外部リンク