Api Doc Bundle Laravel Package

Getting Started

This package is a fork/mirror of nelmio/api-doc-bundle — a Symfony bundle, not a Laravel package. Before anything else, confirm you actually need it: for a Laravel codebase you will spend more time building adapters than writing docs, and dedoc/scramble, knuckleswtf/scribe, or darkaonline/l5-swagger will get you there faster. Use this package only if you are working in Symfony or maintaining a Symfony service.

Minimal steps (Symfony):

composer require mrbulkinaleksey/api-doc-bundle

Register the bundle in config/bundles.php (auto-discovered on Symfony Flex), then create config/packages/nelmio_api_doc.yaml:

nelmio_api_doc:
    documentation:
        info:
            title: My API
            version: 1.0.0
    areas:
        path_patterns: [ ^/api ]

Import the routes (usually in config/routes/nelmio_api_doc.yaml):

app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

Where to look first: the README's "Quick start" and the Areas and Annotations sections — those two concepts drive 80% of day-to-day usage. Then open vendor/nelmio/api-doc-bundle/Controller/ to understand the built-in Swagger UI / JSON controllers you'll be pointing at.

First use case: annotate one controller action with @OA\Get (OpenAPI 3) or the legacy @ApiDoc, clear cache, and load /api/doc. Once that single endpoint renders correctly, expand area by area.

Implementation Patterns

OpenAPI 3 with PHP 8 attributes (recommended over annotations). Declare operations directly on controller methods. This keeps docs next to the code they describe and survives refactors better than a central YAML file.

#[OA\Get(
    path: '/api/users/{id}',
    summary: 'Fetch a user',
    parameters: [new OA\Parameter(name: 'id', in: 'path', required: true, schema: new OA\Schema(type: 'integer'))],
    responses: [new OA\Response(response: 200, description: 'OK')]
)]
public function show(int $id): JsonResponse { ... }

Model/schema extraction. Use @Model / #[Model] (or configure nelmio_api_doc.models.names) to map DTOs and entities into reusable schemas. Register common error payloads once and $ref them everywhere via OA\Schema(ref: '#/components/schemas/Error').

Areas as routing partitions. Define separate areas for public vs admin (different path_patterns, different security schemes, different base paths). This is the cleanest way to produce multiple spec documents from one codebase and to hide internal endpoints from the public doc.

Serialization groups. If endpoints return serialized entities, wire nelmio_api_doc.documentation to reuse Symfony Serializer groups so the emitted schema matches what the serializer actually emits. Misalignment here is the #1 cause of "the docs lie" complaints.

Route/controller decorators for auth. Combine with lexik/jwt-authentication-bundle or symfony/security by adding a securitySchemes block in config, then reference it per-operation (security: [['bearerAuth' => []]]). Do not hand-roll auth docs per endpoint.

CI integration. Export the spec (bin/console nelmio:apidoc:dump --format=json) in CI and diff it against the previous build, or feed it into openapi-diff, Schemathesis, or Dredd for contract testing. This is the highest-value workflow: docs become an artifact, not a page nobody reads.

Swagger UI customization. Point nelmio_api_doc.controller.swagger_ui at a custom template to brand the UI, prefill the server URL, or disable the "try it out" button on production.

Gotchas and Tips

• Symfony-only. There is no service provider, no Artisan command, no Laravel route registration. If you are in Laravel, treat this as unavailable and pick a Laravel-native alternative.
• Unmaintained fork (0 stars, last release 2023-05-26). The upstream nelmio/api-doc-bundle is actively maintained; prefer it unless this fork has a specific patch you need. Check the diff before adopting, and pin exact versions in composer.json.
• Annotations vs attributes. Older examples in blog posts use zircote/swagger-php annotations, which require doctrine/annotations and break on PHP 8.2+ without implements fixes. Use PHP 8 attributes (#[OA\...]) and swagger-php v4+.
• Cache is aggressive. Specs are cached in the Symfony cache pool; bin/console cache:clear after editing annotations, or set nelmio_api_doc.documentation.cache.enabled: false in dev. In prod, warm the cache during deploy.
• Areas silently swallow endpoints. If a controller does not appear, it is almost always areas.path_patterns excluding it. Use bin/console debug:router and nelmio:apidoc:dump --no-pretty to confirm what the area actually captured.
• Required vs nullable fields. OA\Schema won't infer required from PHP typed properties; you must declare required: ['field'] explicitly, otherwise every consumer generates optional DTOs and validation drifts.
• Response codes need explicit @OA\Response. There is no automatic inference from #[Route] methods; a POST returning 201 will be documented as 200 unless you write it.
• Extension points: custom nelmio_api_doc.model_describers and nelmio_api_doc.documenters services let you hook in proprietary types (money objects, enums, UUID wrappers). Implement ModelDescriberInterface and tag the service; this is where you'd add Laravel-specific adapters if you were porting.
• Debugging a broken spec: dump JSON via bin/console nelmio:apidoc:dump --format=json and pipe through jq / validate at editor.swagger.io. Errors from swagger-php surface here, not in the browser.
• Do not commit generated openapi.json unless it is a release artifact. Regenerate in CI; committed specs rot fast.