Release v0.1.20 — Phase 20: API Documentation

[menvil]

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.

^{Written for commit 100920d. Summary will update on new commits.}

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.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds comprehensive API documentation for the File Converter API by defining a complete OpenAPI 3.1.0 specification, creating a Redoc-powered documentation page, and adding feature tests to validate both the documentation rendering and the OpenAPI contract structure.

Changes

API Documentation and Specification

Layer / File(s)	Summary
OpenAPI 3.1.0 Specification docs/api/openapi.yaml	Defines the complete OpenAPI contract with server URLs, nine REST endpoint paths (converters, file upload, conversion management, credits), bearer token security scheme, component schemas for errors and domain models, and shared error response objects.
Documentation Routes and Blade View routes/web.php, resources/views/docs/api.blade.php	Adds /docs/api route serving a Blade view that renders the API docs with Redoc integration, developer quickstart checklist, curl examples, and authorization notes; adds /docs/api/openapi.yaml route serving the spec file with correct YAML content type.
Test Infrastructure and Dependencies composer.json, tests/Pest.php	Adds symfony/yaml (^7.4) to dev dependencies and creates an openApiSpec() helper that parses the OpenAPI YAML for test access.
API Documentation Page Tests tests/Feature/Docs/ApiDocumentationPageTest.php	Feature tests verify the /docs/api page renders successfully, displays the API title, shows developer quickstart content with upload/create/download workflow steps, includes curl examples for /api/v1/files and /api/v1/conversions endpoints, and is accessible without authentication.
OpenAPI Specification Tests tests/Feature/Docs/OpenApiSpecificationTest.php, tests/Feature/Docs/OpenApiPathsTest.php	Feature tests validate the OpenAPI file structure (existence, required keys openapi/info/paths/components), bearer security scheme (ApiKeyBearer with http type and bearer scheme), required ErrorResponse component schema, all nine API path endpoints with correct HTTP methods, and complete set of domain component schemas.

---

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly references Phase 20 API Documentation, which directly aligns with the main objective of adding OpenAPI specification and public API documentation pages.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/v0.1.20-phase20-api-documentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

tests/Pest.php (1)

55-58: 💤 Low value

Consider documenting potential exceptions in a docblock.

The Yaml::parseFile() call can throw exceptions if the file is missing or the YAML is malformed. While letting exceptions bubble up is acceptable for test helpers (failures signal real problems), a docblock would clarify the function's behavior for future maintainers.

📝 Optional docblock addition

+/**
+ * Parse the OpenAPI specification file.
+ *
+ * `@return` array The parsed OpenAPI spec
+ * `@throws` \Symfony\Component\Yaml\Exception\ParseException If YAML is malformed
+ */
 function openApiSpec(): array
 {
     return Yaml::parseFile(base_path('docs/api/openapi.yaml'));
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/Pest.php` around lines 55 - 58, Document that openApiSpec() calls
Yaml::parseFile which can throw on missing files or malformed YAML; add a
docblock above the openApiSpec function mentioning the possible exceptions (e.g.
`@throws` \Symfony\Component\Yaml\Exception\ParseException and/or `@throws`
\RuntimeException or `@throws` \Throwable) and state that exceptions are
intentionally left to bubble up for tests to fail loudly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api/openapi.yaml`:
- Around line 6-10: The servers list in the OpenAPI spec currently hardcodes
environment-specific URLs; update the servers entry so the default server URL is
deployment-agnostic (use a relative path such as /api/v1) instead of
https://example.com/api/v1 or http://localhost/api/v1 so generated clients and
docs point at the hosting app; edit the servers array in docs/api/openapi.yaml
(the servers block shown) to replace the absolute URLs with a single relative
URL like /api/v1 and keep or adjust the descriptions accordingly.
- Around line 396-398: OpenAPI 3.1 removes the `nullable` keyword; update
OptionField.default and Conversion.result_file to use JSON Schema nullability:
for OptionField.default (symbol: OptionField.default) change the schema from
`nullable: true` to a type that allows null (e.g., type: [ "string", "null" ] or
anyOf with type 'null'), keeping the example; for Conversion.result_file
(symbol: Conversion.result_file) replace `nullable: true` + $ref with an anyOf
that allows either the File schema or null (e.g., anyOf: - $ref:
'`#/components/schemas/File`' - { type: 'null' }). Ensure no `nullable` keywords
remain in the file.

In `@resources/views/docs/api.blade.php`:
- Around line 49-83: The examples in the docs currently hardcode
"https://example.com/api/v1/..." in the curl command blocks, making them
non-portable; replace those literal URLs with the app's runtime base (e.g. use
Blade's url() helper or an injected $apiBase) across every curl snippet (each
occurrence of "https://example.com/api/v1/files",
"https://example.com/api/v1/conversions/estimate",
"https://example.com/api/v1/conversions",
"https://example.com/api/v1/conversions/{id}", and the download URL) so the
snippets render as "{{ url('/api/v1/...') }}" or "$apiBase/api/v1/..." in the
template; ensure the change is applied to all six examples (upload, list
targets, estimate, create conversion, poll status, download) so they remain
copy-pasteable in any environment.

---

Nitpick comments:
In `@tests/Pest.php`:
- Around line 55-58: Document that openApiSpec() calls Yaml::parseFile which can
throw on missing files or malformed YAML; add a docblock above the openApiSpec
function mentioning the possible exceptions (e.g. `@throws`
\Symfony\Component\Yaml\Exception\ParseException and/or `@throws`
\RuntimeException or `@throws` \Throwable) and state that exceptions are
intentionally left to bubble up for tests to fail loudly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 60e31f02-57b5-4243-8806-55408d02e8ff

📥 Commits

Reviewing files that changed from the base of the PR and between 50a5f98 and 8d66b36.

⛔ Files ignored due to path filters (1)

• composer.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• composer.json
• docs/api/openapi.yaml
• resources/views/docs/api.blade.php
• routes/web.php
• tests/Feature/Docs/ApiDocumentationPageTest.php
• tests/Feature/Docs/OpenApiPathsTest.php
• tests/Feature/Docs/OpenApiSpecificationTest.php
• tests/Pest.php

[cubic-dev-ai]

2 issues found across 9 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>