Weave Code
Api Doc Bundle Laravel Package
nelmio/api-doc-bundle
Symfony bundle to generate OpenAPI documentation for your APIs. Provides an interactive docs UI and schema generation driven by PHP 8 attributes. Requires PHP 8.1+ and Symfony 6.4+. Includes migration guides and solid CI support.
Generates documentation for your REST API from attributes
Frequently asked questions about Api Doc Bundle
- Can NelmioApiDocBundle work with Laravel without Symfony, or is it strictly for Symfony apps?
- NelmioApiDocBundle is Symfony-first, but you can use it with Laravel by bridging Symfony components (e.g., `laravel-symfony-bundle`) or generating OpenAPI JSON via CLI for static serving. Native Laravel integration requires workarounds like custom attribute readers or mocking Symfony dependencies.
- What’s the easiest way to add OpenAPI docs to a Laravel API using Nelmio?
- Install via Composer (`composer require nelmio/api-doc-bundle`), configure Symfony components via `laravel-symfony-bundle`, then annotate controllers with PHP 8 attributes (e.g., `#[ApiProperty]`). Use the bundled Swagger UI or export JSON for tools like Redoc. Laravel’s routes must be manually mapped to Symfony’s routing system.
- Does Nelmio support Laravel’s native validation (e.g., Form Requests) or only Symfony’s Validator?
- Nelmio primarily uses Symfony’s Validator, but you can integrate Laravel’s validation by translating Form Request rules to Symfony constraints or using the Symfony Bridge to share validation logic. This may require custom middleware or a service layer to bridge the two systems.
- How do I handle PHP 8 attributes in older Laravel versions (pre-8.40) with Nelmio?
- Laravel 8.40+ natively supports PHP 8 attributes. For older versions, use `phpdocumentor/reflection-docblock` or `rubix/attribute` to parse attributes. Nelmio’s documentation assumes PHP 8.1+, so you’ll need to ensure your Laravel app meets this requirement or implement compatibility layers.
- What’s the performance impact of Nelmio’s Symfony dependencies in a Laravel app?
- Nelmio adds ~50+ Symfony dependencies, increasing bundle size and potential conflicts (e.g., `symfony/property-info` vs. Laravel’s `illuminate/support`). Mitigate this by using Nelmio only for documentation generation (e.g., CLI-based OpenAPI export) or adopting a hybrid approach with static file serving.
- Can I use Nelmio’s Swagger UI in Laravel without Twig, since Laravel uses Blade?
- Nelmio’s Swagger UI relies on Twig templates. For Laravel, you can either serve the Twig templates statically (e.g., via `public/swagger-ui`) or convert them to Blade. Alternatively, generate OpenAPI JSON and use a standalone Swagger UI (e.g., from `npm install swagger-ui-dist`).
- Are there Laravel-native alternatives to NelmioApiDocBundle for OpenAPI docs?
- Yes. For Laravel, consider `darkaj19/swagger` (Laravel 5/6/7) or `spatie/laravel-api-documentation` (modern, attribute-based). These avoid Symfony dependencies and integrate more seamlessly with Laravel’s ecosystem. Nelmio is better suited if you’re already using Symfony or need deep OpenAPI 3.0 compliance.
- How do I migrate from Nelmio 4.x (Swagger 2.0) to 5.x (OpenAPI 3.0) in Laravel?
- Follow Nelmio’s [upgrade guide](https://github.com/nelmio/NelmioApiDocBundle/blob/5.x/UPGRADE-5.0.md) for Symfony-specific changes (e.g., PHP 8.1+, attribute migration). In Laravel, ensure your Symfony Bridge and attribute parsing are updated. Test thoroughly, as OpenAPI 3.0 has stricter schema requirements than Swagger 2.0.
- Will Nelmio’s Symfony updates (e.g., PHP 8.3+) break my Laravel integration?
- Nelmio’s Symfony-centric updates may require manual adjustments in Laravel, especially if using the Symfony Bridge. Monitor Nelmio’s changelog and test updates early. Consider forking or contributing Laravel-specific patches if critical features break. Static OpenAPI generation (via CLI) reduces runtime dependency risks.
- How do I document Laravel’s API resources (e.g., JSON:API) with Nelmio’s OpenAPI?
- Use Nelmio’s `#[ApiResource]` and `#[ApiProperty]` attributes to define schemas for your resources. For complex cases (e.g., polymorphic relationships), extend Nelmio’s type system with custom classes or use Laravel’s `spatie/laravel-data` for DTOs. Validate the OpenAPI output against tools like Swagger Editor to catch inconsistencies.
Weaver
How can I help you explore Laravel packages today?