OpenAPIとはAPI仕様書の標準形式と活用法

OpenAPIとは

OpenAPI（OpenAPI Specification、略称 OAS）とは、HTTP API の仕様を、プログラミング言語に依存しない形で記述するための標準規格です。仕様書によれば、人間と機械の両方が、ソースコードや追加の説明資料を見なくても、サービスの機能を理解できるようにすることを目的としています。

イメージとしては、APIの「設計図」を、決まった書式のファイル（YAML または JSON）で書いておく仕組みです。かつては Swagger という名前で知られていましたが、現在は OpenAPI Initiative が仕様を管理しています。仕様のバージョンは更新されるので、最新の版は公式サイトで確認してください。

基本（仕組み・書き方）

OpenAPI のファイルには、主に次の情報を書きます。

仕様書によれば、paths には相対的なパスを書き、サーバーのURLに付け足して使います。各パスの下に、GET や POST などの操作（Operation）を書き、パラメータ、リクエストの本文、応答、必要な認証を記述できます。操作には operationId という識別子を付けられ、API全体で重複しない必要があります。

書き方の骨格の例です。

openapi: 3.0.3
info:
  title: 顧客API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /customers/{customerId}:
    get:
      operationId: getCustomer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 顧客を返す

上は仕組みを示す簡略例です。使うバージョンの正確な書式は、公式の仕様で確認してください。

OpenAPIの具体例

OpenAPI を書いておくと、次のような作業を自動化できます。

たとえば20個のエンドポイントがあるAPIで、1つあたり説明文書の更新に15分かかっているなら、全部で300分（5時間）です。仕様ファイルから生成する形にすれば、更新作業は仕様ファイルの修正1か所に集約できます。ただし、最初に仕様ファイルを整備する工数は別途かかります。

OpenAPIの実践ステップ

1. 公開したい（または利用したい）APIを決め、既存の仕様書があるか確認する。
2. 提供側なら、まず主要な3〜5個のエンドポイントだけを OpenAPI で記述する。
3. 検証ツールで、書式に誤りがないかを確認する。
4. 閲覧用のドキュメントを生成し、利用者に見える形で公開する。
5. 仕様ファイルを、ソースと一緒にバージョン管理する。
6. 変更の際は、仕様ファイルを先に直し、レビューしてから実装する。

利用側の立場なら、提供元が OpenAPI のファイルを配布していないか探します。あれば、連携ツールやテストツールに読み込むだけで、呼び出しの準備が進みます。

OpenAPIの注意点

• 仕様ファイルと実装がずれると、かえって混乱します。自動テストで検証する仕組みが欠かせません。
• バージョン（3.0系、3.1系など）で書式が違う箇所があります。使うツールが対応するバージョンを確認してください。
• 認証情報の実物（キーなど）を、仕様ファイルに書いてはいけません。
• 仕様ファイルの公開範囲に注意します。内部仕様が含まれる場合は、社外に出さない管理が必要です。

OpenAPIでよくあるミス

• 実装を変えたのに、仕様ファイルを更新しない。
• 応答のエラーパターンを書かず、正常系だけの仕様になる。
• 項目の必須・任意を省略し、利用者が推測で実装する。
• 生成されたコードを手で直し、仕様の再生成で消えてしまう。

OpenAPIのチェックリスト

• 仕様ファイルは YAML または JSON として、構文が正しいか。
• servers、認証方式、エラー応答を記述したか。
• operationId が重複していないか。
• 仕様と実装のずれを、自動で検知できるか。
• 仕様ファイルのバージョン管理と、レビューの手順があるか。

OpenAPIのFAQ（よくある質問）

Q. Swagger と OpenAPI は同じものですか。
A. 仕様としては、OpenAPI が現在の名称です。Swagger は、もともとの仕様や、周辺ツール群の名前として今も使われています。

Q. OpenAPI は REST API だけのものですか。
A. 仕様書では HTTP API 向けの記述形式と位置づけられています。REST の厳密な設計である必要はありません。

Q. 書くのが大変ではありませんか。
A. 最初は負担ですが、ドキュメント、テスト、連携の準備を同じファイルから作れるため、長く運用するAPIほど効果が出やすいです。

筆者の見解（OpenAPI）

OpenAPI の価値は、書式そのものより、仕様を先に合意する文化を作れる点にあると考えます。導入すると、実装後に仕様書を書く手順が、仕様を直してから実装する手順に逆転します。私見では、小さなAPIなら主要な操作だけを書き、使われ方を見ながら広げる進め方が現実的で、最初から全項目を完璧に埋めようとすると続かないと思います。

OpenAPIの関連項目

• API
• REST API
• エンドポイント
• APIゲートウェイ
• GraphQL

出典（一次情報）

• OpenAPI Specification（最新版）
• OpenAPI Initiative