IT 技書の森

API ドキュメント

API の仕様、エンドポイント、リクエスト/レスポンス形式を記述し、開発者の統合を支援するドキュメント

APIドキュメント

API ドキュメントとは

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

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 キー、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 ドキュメントの関連書籍も参考になる。

関連用語