Extended Api Doc Bundle Laravel Package

Getting Started

• Install only after confirming the app already uses nelmio/api-doc-bundle and that the Nelmio UI route works. This package is an overlay, not a replacement for Nelmio.
• Run composer require pbaszak/extended-api-doc-bundle, then register the bundle in config/bundles.php if Symfony Flex does not do it automatically. Use the bundle class from vendor/pbaszak/extended-api-doc-bundle/src/*Bundle.php; the namespace may differ from examples.
• Clear cache and open the existing Nelmio docs route, usually /api/doc or /api/doc.json. The first use case is simple: make a crowded Swagger UI easier to scan by grouping operations under meaningful OpenAPI tags and improving the default Nelmio presentation.
• Look first at the package README, composer.json, Resources/views, Resources/public, and DependencyInjection. Check its Symfony and Nelmio version constraints before assuming compatibility.
• Add or verify OpenAPI tags on a few controllers/actions first. If sorting does not change, inspect the generated OpenAPI JSON to confirm tags are actually present before debugging the bundle.

Implementation Patterns

• Treat tags as the primary documentation structure. Add #[Tag(name: 'Users')], #[Tag(name: 'Billing')], etc. to controllers/actions, or use the equivalent Nelmio/OpenAPI annotation style already used by the project. The package can only sort what Nelmio exposes.
• Keep tag names stable and domain-oriented: Users, Orders, Billing, Admin, rather than controller-class names. This gives day-to-day value when developers scan the docs for a business area.
• Use Nelmio areas for separate audiences, for example a public API area and an internal/admin area. Apply consistent tags inside each area; the package's presentation improvements should be evaluated per area.
• If the bundle ships Twig/CSS overrides, let it override the default Nelmio view and only customize further when needed. For app-specific changes, use standard Symfony bundle template overrides or CSS overrides rather than editing vendor/.
• Make docs review part of the endpoint PR checklist: new route added, OpenAPI operation tagged, docs page checked locally, tag appears in the expected group. This is the main day-to-day workflow for a UI-only improvement.
• In CI, dump or fetch the OpenAPI document and assert that key operations contain expected tags. This catches missing tags before the UI sorting hides the problem in a default/untagged bucket.
• Keep API contract annotations in Nelmio/OpenAPI attributes as the source of truth. Treat this bundle as presentation-layer polish; do not encode business or schema rules in its templates.

Gotchas and Tips

• Low adoption and a 2024 last release are maintenance risks. Pin the package version, test upgrades against the current Nelmio/Symfony versions, and be prepared to fork or copy its Twig/CSS overrides into the app if it becomes unmaintained.
• Sorting is driven by tags, so untagged operations may remain in a default group and appear “unsorted.” Check the generated /api/doc.json first; fix missing tags before investigating the bundle.
• Bundle registration and asset handling are common failure points. After install, run bin/console cache:clear, and if CSS/JS assets are involved, run bin/console assets:install public or the project’s asset build step.
• If the UI does not change, disable the bundle temporarily and compare against stock Nelmio. Then use bin/console debug:twig, bin/console debug:router, and browser dev tools to confirm whether templates, routes, or cached assets are the issue.
• Check whether the bundle exposes configuration or extension points. Many UI-focused bundles do not; if not, customize through Twig overrides, CSS, or a small service decorator rather than patching vendor files.
• Do not rely on this package for API correctness, security, or schema generation. It improves navigation and styling around Nelmio; missing annotations, invalid schemas, and route conflicts remain Nelmio/Symfony problems.