IT 技書の森

OpenAPI

REST API の仕様を YAML/JSON で記述する標準フォーマットで、ドキュメント生成やコード生成に活用される

APIドキュメント

OpenAPI とは

OpenAPI (旧 Swagger) は、REST API の仕様を YAML または JSON で記述する標準フォーマットである。OpenAPI Initiative (Linux Foundation) が管理しており、現行バージョンは OpenAPI 3.1。API のエンドポイント、リクエスト/レスポンスの構造、認証方式を機械可読な形式で定義する。

基本的な仕様書

openapi: 3.1.0
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 注文を作成
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [userId, items]
              properties:
                userId: { type: string }
                items:
                  type: array
                  items: { $ref: '#/components/schemas/OrderItem' }
      responses:
        '201':
          description: 注文が作成された
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '400':
          description: バリデーションエラー

OpenAPI から生成できるもの

生成物 ツール
対話的ドキュメント Swagger UI, Redoc
TypeScript の型定義 openapi-typescript
API クライアント openapi-generator, orval
サーバースタブ openapi-generator
バリデーション openapi-response-validator
モックサーバー Prism

スキーマファースト vs コードファースト

アプローチ 流れ メリット
スキーマファースト OpenAPI 仕様書 → コード生成 フロントエンドとバックエンドが並行開発
コードファースト コード → OpenAPI 仕様書を自動生成 実装が先、素早く開発

API ファーストデザインではスキーマファーストが推奨される。

API Gateway での活用

API Gateway は OpenAPI 仕様書をインポートして API を作成できる。

TypeScript の型生成

npx openapi-typescript openapi.yaml -o src/api-types.ts

import type { paths } from './api-types';

type CreateOrderBody = paths['/orders']['post']['requestBody']['content']['application/json'];
type OrderResponse = paths['/orders']['post']['responses']['201']['content']['application/json'];

OpenAPI 仕様書から TypeScript の型を自動生成し、API クライアントの型安全性を保証する。

現場での応用を知るには関連書籍も役立つ。

関連用語