OpenAPI Specification

OpenAPI
	OpenAPI Specification
開始年	2010年
初版	2011年8月10日
最新版	3.1.0; 2021年2月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とYAMLの両方を扱うことができる^[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)にある。

出典

^ “New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services”. 2023年10月31日時点のオリジナルよりアーカイブ。2023年10月31日閲覧。
^ “OpenAPI Initiative Charter”. OpenAPI Initiative. 2019年11月12日閲覧。
^ “Swagger creator joins SmartBear”. 2019年8月6日閲覧。
^ “SmartBear Assumes Sponsorship of Swagger API Open Source Project”. SmartBear. 2015年3月25日閲覧。
^ “FAQ”. OpenAPI Initiative. 2019年11月12日閲覧。
^ “New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services”. linuxfoundation.org. 2016年4月27日時点のオリジナルよりアーカイブ。2016年4月22日閲覧。
^ OpenAPI Initiative. “OpenAPI Specification”. GitHub. 2019年11月12日閲覧。
^ “The OAI Announces the OpenAPI Specification 3.0.0”. OpenAPIs (2017年7月26日). 2018年4月19日閲覧。
^ Avram (2017年5月6日). “The HTTP API space is Consolidating around OAS”. InfoQ. 2017年5月14日閲覧。
^ “OpenAPI Specification 3.1.0 Available Now”. Linux.com (2021年4月26日). 2021年4月26日閲覧。
^ Charboneau (2021年4月7日). “What's New in OpenAPI 3.1.0?”. Nordic APIs. 2021年4月7日閲覧。
^ “OpenAPI Specification 3.1.0 Released”. OpenAPI Initiative (2021年2月18日). 2021年2月18日閲覧。
^ Sturgeon (2021年2月16日). “Migrating from OpenAPI 3.0 to 3.1.0”. OpenAPI Initiative. 2021年2月16日閲覧。
^ “OpenAPI Specification Version 3.1.0”. GitHub. 2023年11月7日閲覧。
^ ^a ^b ^c “swagger-api/swagger-spec”. GitHub. 2016年6月4日時点のオリジナルよりアーカイブ。2015年12月1日閲覧。
^ Preibisch, Sascha (2018). API Development: A Practical Guide for Business Implementation Success. [Berkeley, CA]: Apress. ISBN 978-1-4842-4140-0. OCLC 1076234393. "Having the Swagger (or for that matter, any other machine-readable) document available, team members can start working on their part of the project at the same time."
^ Hoppe, Johannes (2018年). “Swagger Codegen is now OpenAPI Generator”. Angular.Schule 2019年8月6日閲覧。
^ “Swagger Codegen Fork: Q&A”. OpenAPI Generator 2019年8月6日閲覧。

参考文献

Haupt, F.; Karastoyanova, D.; Leymann, F.; Schroth, B. (2014). A Model-Driven Approach for REST Compliant Services. ICWS 2014. 2014 IEEE International Conference on Web Services. pp. 129–136. doi:10.1109/ICWS.2014.30. ISBN 978-1-4799-5054-6。
Pautasso, Cesare (2021). Beautiful APIs. LeanPub. pp. 100. https://leanpub.com/beautiful-apis/