- How do I get started with Documentator in a Laravel 13 project?
- Install via Composer (`composer require tsitsishvili/documentator`), then visit `/docs`—no config needed for basic usage. For custom routes or grouping, publish the config with `php artisan vendor:publish --tag=documentator-config`. The raw OpenAPI spec is available at `/docs/openapi.json`.
- Does Documentator support Laravel’s `abort()` or custom exceptions in API docs?
- Yes, the latest version auto-infers error responses for `abort()`, `abort_if()`, `abort_unless()`, and HTTP exceptions like `HttpResponseException`. For custom exceptions, use `@Schema` attributes to refine the inferred schema. Run `php artisan documentator:explain` to debug edge cases.
- Can I enforce OpenAPI schema consistency in CI/CD to prevent breaking changes?
- Absolutely. Use the `--fail-on=breaking` flag with `php artisan documentator:check --against=previous_spec.json` in your CI pipeline. This blocks non-additive schema changes, ensuring backward compatibility. Combine it with `spectral` for custom OpenAPI linting rules.
- How does Documentator handle conditional fields (e.g., `when()`, `mergeWhen()`) in FormRequests?
- Conditional fields are now correctly marked as *optional* (not nullable) in the OpenAPI schema, aligning with Laravel’s validation logic. Nested conditional logic (e.g., `mergeWhen` inside `when`) may require manual testing or `@Schema` annotations for full accuracy.
- Will Documentator break existing Postman collections or Swagger UI configs if I regenerate the OpenAPI spec?
- Regenerated specs may introduce breaking changes (e.g., required fields, error responses). Mitigate this by running `php artisan documentator:check --fail-on=breaking` pre-upgrade and comparing `previous_spec.json` with the new spec. Use `--fail-on=breaking` in CI to block non-additive changes.
- How does Documentator infer response schemas for Spatie Data/Eloquent models?
- Documentator preserves PHPDoc descriptions, `@var` types, and examples from Spatie Data/Eloquent models, improving schema fidelity. For complex nested structures (e.g., `Optional` or `Lazy` properties), test the generated schema or use `@Schema` attributes to override defaults.
- Can I use Documentator with Laravel 11 or PHP 8.1?
- No, Documentator requires **PHP 8.2+** and **Laravel 12 or 13**. The package leverages modern PHP features (e.g., enums, attributes) and Laravel’s updated routing system. Downgrading is not supported.
- How do I debug why a route’s documentation is incorrect or missing?
- Use the `php artisan documentator:explain` command to inspect the inference pipeline for a specific route. This shows how Documentator derived the schema from routes, PHPDoc, FormRequests, and middleware. For legacy code (e.g., custom route registration), manual `@Schema` annotations may be needed.
- Does Documentator support API versioning (e.g., `/api/v1/users`)?
- Yes, Documentator auto-detects versioned routes and groups them in the UI. Configure `grouping.sections` in the published config to split the spec by version (e.g., `/docs/api/v1/openapi.json`). The built-in explorer supports filtering and navigation by route sections.
- Are there alternatives to Documentator for Laravel API docs?
- Alternatives include **Laravel API Docs** (basic PHPDoc-based), **Spatie’s OpenAPI** (more manual), or **Swagger UI** with custom annotations. Documentator stands out for its **zero-config inference**, **OpenAPI 3.1 compliance**, and **interactive UI** without external dependencies. For teams needing stricter control, consider combining it with `spectral` for custom validation rules.