OpenAPI Specification
 | この記事は別の言語から大ざっぱに翻訳されたものであり、場合によっては不慣れな翻訳者や機械翻訳によって翻訳されたものかもしれません。 |
| OpenAPI Specification | |
| 開始年 | 2010年 |
|---|---|
| 初版 | 2011年8月10日 |
| 最新版 |
3.1.0 2021年2月15日 |
| ウェブサイト |
openapis |
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”. 31 October 2023時点のオリジナルよりアーカイブ。31 October 2023閲覧。
- ^ “OpenAPI Initiative Charter”. OpenAPI Initiative. 12 November 2019閲覧。
- ^ “Swagger creator joins SmartBear”. August 6, 2019閲覧。
- ^ “SmartBear Assumes Sponsorship of Swagger API Open Source Project”. SmartBear. 2015年3月25日閲覧。
- ^ “FAQ”. OpenAPI Initiative. 12 November 2019閲覧。
- ^ “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. 12 November 2019閲覧。
- ^ “The OAI Announces the OpenAPI Specification 3.0.0”. OpenAPIs (July 26, 2017). 2018年4月19日閲覧。
- ^ Avram (May 6, 2017). “The HTTP API space is Consolidating around OAS”. InfoQ. 2017年5月14日閲覧。
- ^ “OpenAPI Specification 3.1.0 Available Now”. Linux.com (April 26, 2021). 2021年4月26日閲覧。
- ^ Charboneau (April 7, 2021). “What's New in OpenAPI 3.1.0?”. Nordic APIs. 2021年4月7日閲覧。
- ^ “OpenAPI Specification 3.1.0 Released”. OpenAPI Initiative (February 18, 2021). 2021年2月18日閲覧。
- ^ Sturgeon (February 16, 2021). “Migrating from OpenAPI 3.0 to 3.1.0”. OpenAPI Initiative. 2021年2月16日閲覧。
- ^ “OpenAPI Specification Version 3.1.0”. GitHub. November 7, 2023閲覧。
- ^ a b c “swagger-api/swagger-spec”. GitHub. 4 Jun 2016時点のオリジナルよりアーカイブ。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 August 6, 2019閲覧。
- ^ “Swagger Codegen Fork: Q&A”. OpenAPI Generator August 6, 2019閲覧。
参考文献
[編集]- 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
関連項目
[編集]外部リンク
[編集]- OpenAPI Initiative (OAI) Webサイト
- API Specifications Conference (ASC) Webサイト
- Swagger Webサイト
- OpenAPI Specification on GitHub
- Directory of OpenAPI definitions
- OpenAPI Editor: A rich UI Eclipse OpenAPI (OAS) editor and studio to design, develop and test OAS3/OpenAPI
- OpenAPI for EDI the Electronic data interchange
- Petstoreクライアント／サーバ仕様の例