OpenAPI・Swagger おーぷんえーぴーあい・すわっがー
API仕様REST APIドキュメント自動生成スキーマコード生成
OpenAPI・Swaggerについて教えて
OpenAPI・Swaggerとは
OpenAPI仕様（OAS）は、REST APIのインターフェースを機械・人間が読める形式で記述するための標準仕様です。もともとはSmartBear社が開発した「Swagger」というツールセットの仕様部分が、2016年にLinux Foundation傘下のOpenAPI Initiativeに寄贈され「OpenAPI」という名称になりました。現在もSwaggerという名称はツール群（Swagger UI・Swagger Editor・Swagger Codegen）として残っています。
OpenAPI仕様で書かれたYAML/JSONファイルには、エンドポイント一覧・HTTPメソッド・リクエスト/レスポンスのデータ構造・認証方法などが記述されます。これを使うと：
- Swagger UIで視覚的に見やすいAPIドキュメントを自動生成
- Swagger Codegen / OpenAPI Generatorで各言語のクライアントSDKを自動生成
- API設計段階（Design-First）で仕様を共有し、実装前に合意形成
発注側にとっては「OpenAPIで仕様書を提供してください」と一言言うだけで、標準化された仕様書が手に入り、他システムとの連携もスムーズになります。
OpenAPI仕様の主要要素
| 要素 | 内容 | 例 |
|---|---|---|
| paths | APIエンドポイント一覧 | /orders, /users/{id} |
| components/schemas | データ構造の定義 | Order, User, Error |
| requestBody | リクエストの形式・必須項目 | POSTで送るJSONの構造 |
| responses | レスポンスの形式・ステータス | 200 OK, 404 Not Found |
| securitySchemes | 認証方式の定義 | Bearer Token, API Key |
| servers | APIのベースURL | https://api.example.com/v1 |
歴史と背景
- 2011年 — Tony TamがSwaggerを開発。REST API記述の先駆けとなる
- 2014年 — Swagger 2.0リリース。事実上の業界標準として広まる
- 2016年 — SmartBear社がSwaggerの仕様部分をOpenAPI Initiativeに寄贈。「OpenAPI Specification」に改称
- 2017年 — OpenAPI 3.0リリース。Swagger 2.0から大幅に機能強化
- 2021年 — OpenAPI 3.1リリース。JSON Schemaとの完全互換を実現
- 2023年現在 — AWS・Google・Microsoft・GitHubなど主要プラットフォームのほぼすべてがOpenAPIで仕様を公開
OpenAPI仕様書の例
openapi: 3.0.0
info:
title: 注文管理API
version: 1.0.0
paths:
/orders/{id}:
get:
summary: 注文を取得する
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
properties:
id:
type: integer
amount:
type: number
status:
type: stringOpenAPIのワークフロー
関連する規格・RFC
| 規格・RFC番号 | 内容 |
|---|---|
| OpenAPI Specification 3.1 | OpenAPI Initiativeが管理する最新の公式仕様 |
| JSON Schema Draft 2020-12 | OpenAPI 3.1がスキーマ定義に採用している標準 |
| RFC 8259（JSON） | OpenAPIで使用されるJSONフォーマットの仕様 |