API ドキュメント

API ドキュメントとは

API ドキュメントは、API のエンドポイント、リクエスト/レスポンス形式、認証方法、エラーコードを記述し、API を利用する開発者の統合を支援するドキュメントである。良い API ドキュメントがあれば、開発者はサポートに問い合わせずに API を利用できる。

OpenAPI (Swagger) による自動生成

OpenAPI (Swagger) による 自動生成の例を示す。

# openapi.yaml
openapi: 3.0.3
info:
  title: Order API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 注文を作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 注文が作成された
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: バリデーションエラー

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [userId, items]
      properties:
        userId:
          type: string
          example: "user-123"
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'

OpenAPI 仕様書から Swagger UI や Redoc で対話的なドキュメントを自動生成できる。

良い API ドキュメントの要素

良い API ドキュメントの要素を以下に示す。

要素	内容
エンドポイント一覧	パス、メソッド、説明
リクエスト形式	ヘッダー、パラメータ、ボディのスキーマ
レスポンス形式	ステータスコード、ボディのスキーマ
認証方法	API キー、JWT、OAuth の設定方法
エラーコード	エラーレスポンスの形式と対処法
サンプルコード	curl、JavaScript、Python での呼び出し例
レート制限	リクエスト制限と 429 レスポンスの説明

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

コードファーストとスキーマファーストを以下にまとめる。

アプローチ	流れ	メリット
スキーマファースト	OpenAPI 仕様書 → コード生成	API 設計が先、ドキュメントが常に最新
コードファースト	コード → OpenAPI 仕様書を自動生成	実装が先、素早く開発

API ファーストデザインではスキーマファーストが推奨される。OpenAPI 仕様書を先に書き、フロントエンドとバックエンドが並行開発できる。

ドキュメントの自動テスト

ドキュメントの自動テストのコード例を示す。

// OpenAPI 仕様書とレスポンスの整合性をテスト
import { createResponseValidator } from 'openapi-response-validator';

const validator = createResponseValidator(openapiSpec);

test('POST /orders returns valid response', async () => {
  const res = await request(app).post('/orders').send(orderData);
  const errors = validator.validateResponse('post', '/orders', res.status, res.body);
  expect(errors).toBeNull();
});

API Gateway での活用

API Gateway は OpenAPI 仕様書をインポートして API を作成できる。仕様書がそのまま API の定義になる。

API ドキュメントの関連書籍も参考になる。