Skip to main content

OpenAPI

OpenAPI 3.0 は、RESTful API の設計、構築、ドキュメント化、および利用を標準化するための仕様です。これは、人間と機械の両方が理解できる形式で API を記述する方法を定義しています。これにより、さまざまなツールやサービスが API を自動的に解析し、活用できるようになります。

OpenAPI 3.0 の主な特徴​

OpenAPI 3.0 の特徴は多岐にわたりますが、特に重要なポイントは以下の通りです。

  • RESTful API の記述: API のエンドポイント、HTTP メソッド、パラメータ、リクエストとレスポンスのスキーマなどを詳細に記述できます。
  • YAML または JSON 形式: YAML または JSON フォーマットで記述するため、人間にとって読みやすく、機械にとっても解析しやすい形式です。
  • 再利用可能なコンポーネント: $ref を使用して、スキーマ、パラメータ、レスポンスなどの共通のコンポーネントを再利用できます。これにより、仕様書がより簡潔で管理しやすくなります。
  • セキュリティの定義: API の認証方式 (OAuth2、API キーなど) を定義し、ドキュメントに含めることができます。
  • ドキュメント生成: OpenAPI 仕様書から、インタラクティブな API ドキュメントを自動生成するツールが豊富に存在します。これにより、開発者は API の使い方を簡単に理解できます。
  • コード生成: 仕様書からクライアントサイドやサーバーサイドのコードを自動生成できます。これにより、開発時間を短縮し、ヒューマンエラーを減らすことができます。

OpenAPI 3.0 の構成要素​

OpenAPI 仕様書は、主に以下の構成要素から成り立っています。

  • openapi: 使用している OpenAPI のバージョンを指定します。
  • info: API のタイトル、バージョン、説明などのメタ情報を記述します。
  • servers: API がデプロイされているサーバーの URL を指定します。
  • paths: API のエンドポイントを定義します。各エンドポイントには、get、post、put などの HTTP メソッドが含まれます。
  • components: スキーマ、パラメータ、レスポンス、ヘッダーなど、再利用可能なオブジェクトを定義します。
  • security: API のセキュリティ要件を定義します。

Swagger との関係​

OpenAPI は、元々 Swagger という名前で知られていました。2015 年に SmartBear Software が Linux Foundation に寄贈した際に、仕様の名前が OpenAPI Specification に変更されました。

現在、OpenAPI は仕様そのものを指し、Swagger は仕様に基づいたツール群 (Swagger UI、Swagger Editor など) を指すことが一般的です。

OpenAPIの変遷について説明して​

OpenAPIの歴史は、もともと「Swagger」という名前で始まりました。Swaggerは、APIのドキュメント生成を自動化するために2010年に開発された仕様とツールのセットです。その使いやすさから広く普及し、RESTful APIのデファクトスタンダードとなりました。

SwaggerからOpenAPIへ​

2015年、Swaggerの仕様はLinux Foundationに寄贈され、「OpenAPI Initiative (OAI)」が設立されました。この動きは、特定の企業に依存しない、よりオープンで中立的な仕様として発展させることを目的としていました。

その結果、Swaggerの仕様部分は「OpenAPI Specification (OAS)」と名称が変更されました。しかし、「Swagger」という名前は、仕様に基づいたツール群（Swagger UI、Swagger Editor、Swagger Codegenなど）のブランドとして引き続き使われています。

主なバージョンの変遷​

OpenAPIは、Swagger時代から今日に至るまで、いくつかの主要なバージョンアップを経験しています。

  • Swagger 2.0: OpenAPI Initiativeが設立される前のバージョンで、この仕様はYAMLまたはJSONで記述され、swagger: "2.0"というキーで始まります。
  • OpenAPI 3.0: 2017年にリリースされたメジャーバージョンアップです。これは、Swagger 2.0からの大きな変更点を含んでおり、より簡潔で構造化された仕様になりました。
    • swagger: "2.0"がopenapi: "3.0.0"に変更されました。
    • APIのセキュリティ定義がより柔軟になりました。
    • componentsセクションが導入され、共通のコンポーネントの再利用性が向上しました。
    • 複数のサーバーURLを定義できるようになりました。
  • OpenAPI 3.1: 2021年にリリースされたバージョンで、JSON Schema仕様との互換性が向上しました。これにより、より高度なスキーマ定義が可能になりました。

このように、OpenAPIはSwaggerから発展し、ベンダーニュートラルな仕様として継続的に進化しています。これにより、APIのエコシステム全体での相互運用性と標準化が促進されています。