#291 Release v0.1.20 — Phase 20: API Documentation

Summary

• OpenAPI 3.1.0 specification (docs/api/openapi.yaml) documenting all 9 Phase 19 API endpoints
• Public /docs/api page with Redoc UI, developer quickstart, and curl examples
• 19 documentation tests across 3 test files

Changes (CONV-313–329)

• CONV-313 — Create OpenAPI specification skeleton
• CONV-314 — Add OpenAPI validation test (symfony/yaml, openApiSpec() helper)
• CONV-315 — Document API authentication (Bearer scheme)
• CONV-316 — Document standard API errors (ErrorResponse, ErrorObject, reusable responses)
• CONV-317 — Document GET /converters
• CONV-318 — Document GET /converters/{source}/{target}/schema
• CONV-319 — Document POST /files
• CONV-320 — Document GET /files/{file}/targets
• CONV-321 — Document POST /conversions/estimate
• CONV-322 — Document POST /conversions
• CONV-323 — Document GET /conversions/{conversion}
• CONV-324 — Document GET /conversions/{conversion}/download
• CONV-325 — Document GET /credits/balance
• CONV-326 — Add /docs/api route + Redoc UI view
• CONV-327 — Add developer quickstart section
• CONV-328 — Add curl examples
• CONV-329 — Add final smoke tests

Test plan

• 620 tests passing (composer test)
• composer lint passes
• npm run build passes
• /docs/api is public (no auth required)
• No real secrets in docs
• No undocumented future endpoints

🤖 Generated with Claude Code

---

Summary by cubic

Publish public API docs: an OpenAPI 3.1 spec and a Redoc-powered /docs/api page covering all Phase 19 endpoints. Includes follow-up fixes for OpenAPI 3.1 compliance and more robust docs, completing CONV-313–329.

• New Features

  • OpenAPI 3.1 spec at docs/api/openapi.yaml documenting converters, files, conversions, and credits (9 endpoints).
  • Public /docs/api with Redoc UI, developer quickstart, and curl examples; spec served at /docs/api/openapi.yaml.
  • 19 tests validate spec parsing and public docs content; added symfony/yaml (dev) to parse the spec.

• Bug Fixes

  • OpenAPI 3.1 compliance: use relative server URL /api/v1; fix nullability with anyOf (e.g., Conversion.result_file); set OptionField.default to ['string','null'].
  • Docs hardening: use dynamic curl URLs via url(); pin Redoc CDN to 2.x.

Summary by CodeRabbit

Documentation

• New API documentation page with comprehensive OpenAPI 3.1.0 specification.
• Includes step-by-step developer quickstart, curl examples, and full endpoint documentation.
• Covers file conversion operations, bearer token authentication, and credit balance management.
• Interactive documentation viewer for easy API exploration.