OpenAPI準拠・RFC 9457対応リファクタリングの実施について

概要

utayomiのAPIをOpenAPI 3.1.0仕様に準拠させ、エラーレスポンスをRFC 9457（Problem Details for HTTP APIs）に統一するリファクタリングを実施しました。合わせてエンドポイントの命名規則を単数形に統一し、Spectralによる自動Lintを導入しました。

変更内容

• エラーレスポンスをRFC 9457準拠の application/problem+json 形式に統一
• エンドポイントパスを単数形に変更（/api/keys → /api/key、/api/v1/speakers → /api/v1/speaker）
• OpenAPI 3.1.0仕様書（openapi.yaml）を新規作成
• Spectral（API Lintツール）を導入
• エラーメッセージ・ログメッセージを単一ファイルに一元管理

新しいエラーレスポンス形式

全てのAPIエラーレスポンスは以下のRFC 9457形式で返されます。Content-Typeは application/problem+json です。

{
  "type": "https://utayomi.com/errors/validation-error",
  "title": "Bad Request",
  "status": 400,
  "detail": "リクエストボディが不正です",
  "instance": "/api/v1/synthesis",
  "errors": [...]
}

エンドポイントの変更

ユーザーへの影響

• APIキー管理のエンドポイントパスが変更されました（/api/keys → /api/key）
• スピーカー一覧のエンドポイントパスが変更されました（/api/v1/speakers → /api/v1/speaker）
• エラーレスポンスのJSON構造が変更されました（RFC 9457形式）
• 既存のAPIキーはそのままご利用いただけます