本文へスキップ
← 記事一覧に戻る

OpenAPI Specification（OAS）

#勉強#OpenAPI Specification（OAS）#openAPI#swagger

OpenAPI Specification（OAS）とは

OpenAPI Specification（OAS）は、RESTful APIのインターフェース（仕様）を記述するための標準的なフォーマットです。 一言で言うと、「このAPIにはどんな機能があって、どう呼び出せばどんな結果が返ってくるのか」を、人間にもコンピューターにも読みやすい形式（YAMLやJSON）で定義したものです。

なぜ重要なのか？

従来、APIの仕様書はExcelやWikiなどで作成されていましたが、これには「実装と仕様書がズレる」「手作業での更新が大変」という課題がありました。OpenAPIを採用することで、以下のことが自動化・標準化されます。

  • ドキュメントの自動生成: 定義ファイルから、ブラウザで確認・テストができるリッチなドキュメント（Swagger UIなど）を自動作成できます。

  • コードの自動生成: クライアント側のライブラリやサーバー側のスタブコードを自動生成でき、開発効率が劇的に向上します。

  • モックサーバーの構築: 実装を待たずに、フロントエンド開発者がテストに使える偽のAPI（モック）を即座に用意できます。

具体的に何を書くのか？

主に以下の情報を記述します。

項目 内容
Basic Info APIの名前、バージョン、説明など
Paths エンドポイント（/usersなど）と、利用可能なメソッド（GET, POSTなど）
Parameters パスパラメータ、クエリパラメータ、ヘッダーの情報
Responses ステータスコード（200, 404など）と、返却されるデータの構造
Components 共通で利用するデータモデル（Userオブジェクトなど）の定義

記述例（YAML形式）

openapi: 3.0.0
info:
  title: サンプルAPI
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: ユーザー情報を取得する
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }

OpenAPIとSwaggerの違い

よく混同されますが、現在は以下のように使い分けられています。

  • OpenAPI: 仕様（規格）そのものの名称。

  • Swagger: OpenAPIを扱うためのツール群（Swagger Editor, Swagger UI, Swagger Codegenなど）のブランド名。

元々は「Swagger仕様」と呼ばれていましたが、標準化団体に寄贈された際に「OpenAPI Specification」と改名されました。 現在、多くの開発現場では v3.0 または v3.1 が主流として使われています。

OpenAPIとSwaggerについて

「OpenAPI」と「Swagger」は非常に混同されやすい言葉ですが、結論から言うと 「ルール（仕様）」と「道具（ツール）」の関係 です。 以前はどちらも「Swagger」と呼ばれていましたが、現在は明確に区別されています。

OpenAPIとSwaggerの違い

一言で表すと以下のようになります。

  • OpenAPI (Specification): APIの設計図を書くための 「ルール・規格」 です。YAMLやJSON形式で「どう書くべきか」を定めた標準仕様を指します。

  • Swagger (Tools): OpenAPIというルールに基づいて、APIを設計・ビルド・ドキュメント化するための 「ツールのセット」 です。SmartBear社によって開発されています。

ヒント

歴史的背景: 元々はSmartBear社が「Swagger」という名前で仕様とツールの両方を開発していました。その後、仕様の部分だけが標準化団体（OpenAPI Initiative）に寄贈され、「OpenAPI Specification (OAS)」と改名されました。

代表的なSwaggerツール

OpenAPI形式で書かれた定義ファイル（openapi.yamlなど）を読み込んで、以下のような便利な機能を提供します。

ツール名 役割
Swagger UI 定義ファイルから、ブラウザで確認できるインタラクティブな説明書を生成します。ボタンを押すだけで実際にAPIリクエストを試せます。
Swagger Editor ブラウザ上でOpenAPIの定義を記述・編集するためのエディタです。リアルタイムでプレビューが確認できます。
Swagger Codegen 定義ファイルから、各言語（Java, Python, TypeScriptなど）のクライアントコードやサーバーの雛形を自動生成します。
np

どちらの言葉を使えばいい？

  • APIの仕様書をOpenAPI形式で書く」：正しい（規格を指しているため）

  • 「Swagger UIでAPIの動作確認をする」：正しい（具体的なツールを指しているため）

  • 「このプロジェクトはSwaggerを使っている」：一般的（ツール群を総称して使われることが多い）

現代の開発現場では、 「OpenAPIという標準ルールに従って、Swaggerというツールを使って効率化する」 というのが一般的なスタンスです。

← 記事一覧に戻る