Weave Code
Api Doc Bundle Laravel Package
nelmio/api-doc-bundle
NelmioApiDocBundle generates clean, accurate API documentation for your Symfony applications using PHP 8 attributes and OpenAPI 3.0, with support for FrankenPHP worker mode and long-running workers.
Generates documentation for your REST API from attributes
Frequently asked questions about Api Doc Bundle
- Can I use NelmioApiDocBundle in a Laravel application?
- NelmioApiDocBundle is designed for Symfony, not Laravel, so it is not a drop-in solution. You would need to bridge Symfony components such as routing, property_info, type_info, validation, events, and Twig into Laravel, which adds significant complexity and risk. For most Laravel projects, a Laravel-native OpenAPI tool like darkaonline/l5-swagger or zircote/swagger-php is a better fit. If you must use it, consider generating docs via CLI and serving static OpenAPI JSON.
- What PHP and Symfony versions does NelmioApiDocBundle require?
- NelmioApiDocBundle 5.x requires PHP 8.1 or higher and Symfony 6.4 or higher. It removed legacy annotation support in favor of PHP 8 attributes and now focuses on OpenAPI 3.0. Laravel projects on older PHP versions would need to upgrade PHP before considering integration. Check the bundle's UPGRADE guides for version-specific changes.
- How do I install NelmioApiDocBundle with Composer?
- Install it with composer require nelmio/api-doc-bundle. In Symfony, you then register the bundle and configure it via nelmio_api_doc.yaml. In Laravel, Composer installation alone is not enough because Laravel does not natively register Symfony bundles or load their YAML configuration. You would need a bridge or manual service provider setup, which is not officially supported.
- Does NelmioApiDocBundle work with Laravel routes and controllers?
- No, NelmioApiDocBundle relies on Symfony's Route component and its event system to discover and document endpoints. Laravel uses its own router and middleware pipeline, so you would need to map Laravel routes into Symfony-style routes or write custom extractors. This manual synchronization is fragile and adds maintenance overhead. Laravel-native documentation tools avoid this mismatch.
- What are the best alternatives to NelmioApiDocBundle for Laravel API documentation?
- For Laravel, darkaonline/l5-swagger and zircote/swagger-php are common choices because they integrate with Laravel's routing and PHP attributes. spatie/laravel-data can help define DTOs and schemas, and some teams combine it with OpenAPI generators. If you need Swagger UI or ReDoc, Laravel packages provide Blade-friendly views instead of Twig templates. These alternatives avoid pulling in Symfony's property_info and type_info components.
- How do I generate OpenAPI 3.0 docs from PHP 8 attributes in Laravel?
- NelmioApiDocBundle generates OpenAPI 3.0 from PHP 8 attributes, but it is Symfony-centric and expects Symfony's attribute readers and metadata components. In Laravel, use zircote/swagger-php with attributes or darkaonline/l5-swagger, which are built for Laravel's ecosystem. Nelmio would require custom attribute parsing, route mapping, and mocked Symfony services, making it impractical for most teams. Treat Nelmio as a Symfony-only option unless you are prepared to maintain a bridge.
- Is NelmioApiDocBundle compatible with FrankenPHP worker mode?
- Yes, NelmioApiDocBundle runs under FrankenPHP worker mode and other long-running workers. The bundle documents this support in its FrankenPHP and long-running workers guide. However, this compatibility is tested in Symfony applications, not Laravel. In Laravel, worker-mode compatibility would also depend on how you bridge Symfony services and handle state.
- What Symfony dependencies does NelmioApiDocBundle bring into a Laravel project?
- It pulls in Symfony components for routing, dependency injection, property_info, type_info, validation, events, and Twig, among others. Laravel does not provide these natively, so you would need laravel-symfony-bundle or custom replacements. This can introduce dozens of Symfony packages, increase bundle size, and create conflicts with Illuminate components. The integration risk is high unless documentation generation is isolated as a CLI-only task.
- How do I configure NelmioApiDocBundle in Laravel's config directory?
- NelmioApiDocBundle uses Symfony-style YAML configuration, typically nelmio_api_doc.yaml, not Laravel's config/*.php files. Laravel would need a YAML loader or a custom service provider to translate configuration into Symfony's container parameters. The bundle also expects Symfony's dependency injection container and bundle extension system. This is not a native Laravel workflow and requires extra glue code.
- Is NelmioApiDocBundle production-ready and maintained for Laravel APIs?
- NelmioApiDocBundle is actively maintained and production-ready for Symfony APIs, with CI, Codecov, and upgrade guides. It is not officially supported or tested for Laravel, so production use in Laravel carries integration and maintenance risk. Symfony-centric updates could break your Laravel bridge unless you fork or contribute upstream. For Laravel APIs, choose a Laravel-native documentation package with a clearer support path.
Weaver
How can I help you explore Laravel packages today?