OpenAPI Specification

OpenAPI Specificationとは

OpenAPI Specification（OAS、以前はSwagger Specificationとして知られていました）は、Webサービスのインターフェースを記述するための機械可読な仕様です。これにより、APIの設計、生成、消費、可視化が効率的に行えます。OASはAPIの正式な記述であり、ツールがコード、ドキュメント、テストケースなどを生成するために利用されます。

歴史

OASの歴史は、2010年初めにトニー・タム氏によって開始されたSwaggerの開発に遡ります。Swaggerは当初、オンライン辞書会社Wordnikのプロジェクトでした。

2015年3月、SmartBear SoftwareがReverb Technologies（Wordnikの親会社）からSwagger API仕様を買収しました。同年11月、SmartBearはSwagger仕様をLinux Foundationが後援するOpenAPI Initiativeに寄贈することを発表しました。このイニシアチブには、3scale、Apigee、キャピタル・ワン、Google、IBM、インテュイット、マイクロソフト、PayPal、Restletなどの企業が創設メンバーとして参加しました。

2016年1月1日、Swagger仕様はOpenAPI Specification (OAS)と改名され、新たなGitHubリポジトリに移行しました。2017年7月には、OASのバージョン3.0.0がリリースされました。このリリースでは、代替のRESTful API Modeling Language (RAML)の主要な貢献者であったMuleSoftがOASに参加し、RAMLからOASドキュメントを生成するAPI Modeling Frameworkツールをオープンソース化しました。

2021年2月には、バージョン3.1.0がリリースされました。このバージョンでは、スキーマ語彙の調整、Webhookの記述をサポートする新しい要素の導入、APIライセンスの識別、スキーマ参照と記述の並行利用、再利用可能なコンポーネントライブラリの作成の簡素化などが含まれています。

使用方法

OpenAPIインターフェースファイルに基づいて実装されたアプリケーションは、APIのメソッド、パラメータ、データモデルに関するドキュメントを自動的に生成できます。これにより、ドキュメント、クライアントライブラリ、ソースコードの同期を保つことが容易になります。また、OpenAPIドキュメントを用いてサーバ用のソースコードスタブを生成するプロセスは、スキャフォールディングと呼ばれます。

ソフトウェア工学のプラクティスとの関係

OASは、コントラクト優先開発というパラダイムを支援します。これは、最初にAPIコントラクトを定義し、その後でビジネスロジックをプログラミングするというアプローチです。インターフェースが先に決定されるため、下流の開発者はサーバの動作をモックし、早期にテストを開始することができます。これにより、シフトレフトテストの実践が促進されます。

機能

OpenAPI Specificationは言語に依存しない仕様です。OASは、クライアントがサーバの実装を知らなくても、サーバコードにアクセスしなくても、サービスを理解し、利用することを可能にします。これは、APIの利用をよりシンプルかつ効率的にする上で重要な要素です。

OpenAPIを扱うツール

OpenAPI Initiativeは、OASのバージョン3.0の実装リストを管理しています。SmartBearは、現在もOASツールにSwaggerのブランドを冠しています。

Swagger UIフレームワークを使用すると、開発者と非開発者の両方が、サンドボックスUIを通じてAPIを操作し、APIがパラメータやオプションにどのように反応するかを理解することができます。

SwaggerはとYAMLの両方をサポートし、Swagger Codegenには、OpenAPI定義を解析することで、さまざまな言語のドキュメント、APIクライアント、サーバスタブを生成するテンプレート駆動エンジンが含まれています。

2018年7月には、Swagger Codegenの貢献者たちがOpenAPI Generatorというプロジェクトをフォークし、さらなる開発が進められています。

年次会議

OpenAPI Initiativeは、API Specification Conference (ASC)を毎年開催しています。このイベントは、API Strategy and Practice Conference (APIStrat)として始まり、OpenAPI Initiativeの一部となりました。

まとめ

OpenAPI Specificationは、WebサービスのAPIを効率的に開発・管理するための重要なツールです。APIの設計から実装、テスト、ドキュメントまで、幅広いプロセスをサポートし、開発チーム間の連携を強化し、APIの利用を促進します。コントラクト優先開発を推進し、ソフトウェア開発の効率と品質向上に貢献しています。

OpenAPI Specification