OpenAPI Compliance & RFC 9457 Refactoring

Summary

We refactored the utayomi API to comply with the OpenAPI 3.1.0 specification and unified error responses to the RFC 9457 (Problem Details for HTTP APIs) format. Endpoint naming conventions were also standardized to singular form, and Spectral-based automatic API linting was introduced.

Changes

• Unified error responses to RFC 9457 compliant application/problem+json format
• Changed endpoint paths to singular form (/api/keys → /api/key, /api/v1/speakers → /api/v1/speaker)
• Created OpenAPI 3.1.0 specification (openapi.yaml)
• Introduced Spectral (API lint tool)
• Centralized error messages and log messages into single files

New Error Response Format

All API error responses are now returned in the following RFC 9457 format. The Content-Type is application/problem+json.

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

Endpoint Changes

Impact on Users

• API key management endpoint paths have changed (/api/keys → /api/key)
• Speaker list endpoint path has changed (/api/v1/speakers → /api/v1/speaker)
• Error response JSON structure has changed (RFC 9457 format)
• Existing API keys continue to work as-is