OpenAPI Specification

OpenAPI Specification（以前はSwagger Specificationとして知られていた）は、Webサービスを記述、生成、消費^{[訳語疑問点]}、可視化するための機械可読なインターフェース記述言語の仕様である^[1]。以前はSwaggerフレームワークの一部だったが、2015年に独立したプロジェクトとなり、Linux Foundationのオープンソース共同プロジェクトであるOpenAPI Initiativeが統括している^[2]。

OpenAPI

OpenAPI Specification
開始年	2010年 (2010)
初版	2011年8月10日 (2011-08-10)
最新版	3.1.0 2021年2月15日 (2021-02-15)
ウェブサイト	openapis.org

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)にある。