コンテンツにスキップ

OpenAPI とは？

OpenAPI Specification（以前はSwagger Specification）は、REST APIのAPI記述フォーマットです。OpenAPIファイルを使用すると、API全体を記述できます。これには以下が含まれます。

  • 利用可能なエンドポイント（/users）と各エンドポイントでの操作（GET /users、POST /users）
  • 操作パラメータ 各操作の入力と出力
  • 認証方法
  • 連絡先情報、ライセンス、利用規約、その他の情報。

API仕様はYAMLまたはJSONで記述できます。このフォーマットは習得が容易で、人間と機械の両方にとって読みやすいです。完全なOpenAPI SpecificationはGitHubで確認できます: OpenAPI 3.0 Specification

Swaggerとは？

Swaggerは、OpenAPI Specificationを中心に構築されたオープンソースツールのセットで、REST APIの設計、構築、ドキュメント化、および利用を支援します。主なSwaggerツールには以下が含まれます。

  • Swagger Editor – ブラウザベースのエディタでOpenAPI定義を作成できます。
  • Swagger UI – OpenAPI定義をインタラクティブなドキュメントとしてレンダリングします。
  • Swagger Codegen – OpenAPI定義からサーバスタブとクライアントライブラリを生成します。
  • Swagger Editor Next (ベータ版) – ブラウザベースのエディタでOpenAPIおよびAsyncAPI定義を作成およびレビューできます。
  • Swagger Core – OpenAPI定義の作成、利用、および操作のためのJava関連ライブラリ。
  • Swagger Parser – OpenAPI定義を解析するためのスタンドアロンライブラリ。
  • Swagger APIDom – さまざまな記述言語およびシリアライズ形式でAPIを記述するための単一の統一構造を提供します。

OpenAPIを使用する理由

APIが自身の構造を記述する能力は、OpenAPIにおけるすべての素晴らしさの根源です。一度記述されたOpenAPI仕様とSwaggerツールは、さまざまな方法でAPI開発をさらに推進できます。

  • デザインファーストのユーザー: Swagger Codegenを使用して、APIのサーバスタブを生成します。残りの作業はサーバロジックの実装のみで、APIは公開準備完了です！
  • Swagger Codegenを使用して、40以上の言語でAPIのクライアントライブラリを生成します。
  • Swagger UIを使用して、ユーザーがブラウザで直接API呼び出しを試せるインタラクティブなAPIドキュメントを生成します。
  • 仕様を使用して、API関連ツールをAPIに接続します。たとえば、仕様をSoapUIにインポートして、APIの自動テストを作成します。
  • その他にもたくさん！Swaggerと連携するオープンソースおよび商用ツールをチェックしてください。