- Can oro/api-doc-bundle work with Laravel 8/9/10 or is it only for Symfony?
- While this bundle is a Symfony fork, it can be adapted for Laravel using annotation parsers like `spatie/laravel-annotation-reader` and Symfony components (e.g., `symfony/serializer`). Laravel’s routing and DI systems require abstraction, but the core OpenAPI generation logic remains compatible. Test thoroughly with your Laravel version.
- How do I install oro/api-doc-bundle in a Laravel project?
- Since this is a Symfony bundle, you’ll need to install it via Composer (`composer require oro/api-doc-bundle`) and manually configure it to work with Laravel’s ecosystem. Use `spatie/laravel-annotation-reader` for annotations and bridge Symfony dependencies (e.g., `symfony/http-kernel`) via Laravel’s service container.
- Does this bundle support Laravel’s built-in API resources or only annotations?
- This bundle primarily relies on annotations (e.g., `@ApiDoc`, `@Get`). For Laravel’s API resources, you’ll need to manually map routes or use a third-party annotation parser like `spatie/laravel-annotation-reader` to bridge the gap. Native Laravel resource support isn’t included.
- Will oro/api-doc-bundle work with Lumen or is it Symfony-only?
- Lumen’s lightweight architecture makes integration harder due to missing Symfony components (e.g., SensioFrameworkExtraBundle). You’d need to mock or replace these dependencies, such as using `symfony/serializer` directly or rewriting annotation parsing. Test performance in CI before production.
- How do I configure Swagger UI with this bundle in Laravel?
- The bundle includes Swagger UI out-of-the-box, but you’ll need to route `/doc` to the generated JSON schema (e.g., via Laravel’s `Route::get('/doc', [Controller::class, 'showDoc'])`). Ensure the schema path matches the bundle’s output (default: `/doc.json`). Use middleware to cache responses for performance.
- Are there alternatives to oro/api-doc-bundle for Laravel that don’t require Symfony?
- Yes. Consider `darkajp/l5-swagger` (Laravel-native) or `zircote/swagger-php` for annotation-based docs without Symfony dependencies. These are more lightweight and avoid abstraction overhead. Evaluate your team’s tolerance for Symfony components before choosing this fork.
- How do I handle PHPUnit tests for this bundle in a Laravel project?
- Run the original bundle’s tests (`phpunit`) after installing dev dependencies (`composer install --dev`). For Laravel-specific tests, mock Symfony services (e.g., `Container`, `EventDispatcher`) using Laravel’s testing tools. Focus on edge cases like annotation parsing and route mapping.
- Will this bundle slow down my Laravel API in production?
- The bundle adds minimal overhead for small APIs (<1000 endpoints). For larger APIs, cache the generated OpenAPI JSON (e.g., with `laravel-cache` or Redis) and avoid regenerating docs on every request. Profile with `tideways/xhprof` to isolate bottlenecks.
- Does oro/api-doc-bundle support OpenAPI 3.x or only Swagger 2.0?
- This fork (NelmioApiDocBundle 2.x) primarily outputs Swagger 2.0 specs. For OpenAPI 3.x, consider upgrading to `nelmio/api-doc-bundle:^3.0` (Symfony 5+) or use a Laravel-native tool like `darkajp/l5-swagger`, which supports OpenAPI 3.x natively.
- How do I validate API docs in CI/CD for Laravel?
- Use `swagger-cli` or `openapi-linter` to validate the generated JSON schema in CI. Trigger doc regeneration on annotation changes via Git hooks or `php-cs-fixer`. Store the schema in a `docs/` directory and compare hashes between builds to catch regressions.