Simple Api Doc Bundle Laravel Package

Getting Started

Know what you're actually installing. kreta/simple-api-doc-bundle is a thin Symfony bundle that sits on top of nelmio/api-doc-bundle and applies opinionated defaults so you don't have to hand-wire the full Nelmio configuration. It is not a Laravel package and cannot be dropped into a Laravel app — it registers via AppKernel/bundles.php and depends on Symfony's DI container, routing, and event system. If you are working in Laravel, the honest first step is to stop here and use knuckleswtf/scribe, dedoc/scramble, or l5-swagger instead; the concepts below translate, but the code does not.

Minimal setup (Symfony, if you insist):

1. composer require kreta/simple-api-doc-bundle — expect this to fail on any modern stack. The bundle's last release is 2016-02-01, so its composer.json constraints will almost certainly pin Symfony 2.7/2.8–3.x and PHP 5.5–7.x. On PHP 8 / Symfony 5+ you will need --ignore-platform-reqs and will still likely hit fatal errors.
2. Register the bundle in app/AppKernel.php (or config/bundles.php if it somehow installs on a newer kernel).
3. Import the doc route in app/config/routing.yml:

   nelmio_api_doc:
       resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
       prefix: /api/doc
   

4. Hit /api/doc in dev and confirm the sandbox renders.

Where to look first:

• The DependencyInjection/ extension and Resources/config/*.yml — this is where the "simple" part lives. It tells you exactly which Nelmio options the bundle pre-sets, which is the only real value it adds over plain Nelmio.
• composer.json — read the require block before anything else. It is the single best indicator of whether this package is usable for you.
• The NelmioApiDocBundle docs for the version your constraints resolve to, not the latest. The bundle is a wrapper, so Nelmio's behavior is what you'll actually be debugging.

First use case: annotate one controller action and watch it appear in the sandbox.

/**
 * @ApiDoc(
 *   resource=true,
 *   description="Fetch a single order",
 *   requirements={"id"="\d+"},
 *   output="AppBundle\Entity\Order"
 * )
 */
public function getOrderAction($id) { ... }

If that renders correctly, you understand the whole package. Everything else is Nelmio.

Implementation Patterns

Treat it as a config preset, not a framework. The bundle's job is to reduce boilerplate around Nelmio. The day-to-day pattern is: keep business annotations on controllers, keep global doc config in the bundle's YAML, and never fork the bundle to change behavior — override via Nelmio's own config keys, which take precedence or can be merged.

Annotation-driven docs co-located with routes. The dominant workflow is @ApiDoc on each action, with input=/output= pointing at form types or entities so Nelmio reflects the schema. For a team, this is the pattern that scales best because the doc lives next to the code it describes and fails review when it drifts. Pair it with route requirements (requirements={"id"="\d+"}) so the sandbox validates parameters instead of accepting anything.

Areas for versioned or multi-audience APIs. Nelmio's "areas" concept lets you split docs by route prefix or firewall (default, internal, v2). With this bundle you configure areas in YAML and then annotate controllers with @ApiDoc(views={"default"}). Use this when you have public and partner APIs sharing a codebase — it is the cleanest way to avoid leaking internal endpoints into public docs.

Docs as a CI artifact, not just a dev page. The highest-leverage integration is dumping the spec in CI and diffing it:

php app/console api:doc:dump --format=json > build/openapi.json

Commit the dump, fail the build on unexpected diffs, and feed it to client-SDK generators or contract tests. This turns the bundle from a convenience into a governance tool — and it's the one pattern that survives even if you later rip the bundle out and use Nelmio directly.

Sandbox in dev, spec in prod. Serve the interactive sandbox (/api/doc) only in dev, gated behind the dev firewall, but expose the raw JSON dump in prod behind auth for gateway import (Kong, AWS API Gateway). The bundle makes this easy because the dump command and the HTML route are separate concerns.

Progressive migration to OpenAPI 3. Because this bundle pins old Nelmio, the realistic long-term pattern is: keep it running while you migrate annotations to zircote/swagger-php @OA\* annotations or PHP 8 attributes, then switch to NelmioApiDocBundle v4+, which speaks OpenAPI 3 natively. Do the annotation migration first, the bundle swap second — otherwise you're debugging two moving parts at once.

Laravel equivalent pattern. If you're translating this to a Laravel codebase, the equivalent workflow is: attribute-based annotations on controllers (#[OA\Get(...)] via l5-swagger), an artisan command to dump the spec in CI, and a route gated to non-production for the UI. The architectural lesson — co-locate docs with routes, dump in CI, gate the UI — carries over completely; only the package names change.

Gotchas and Tips

Adoption risk is the headline. Zero stars, zero dependents, and a final release in February 2016 mean this package is effectively abandoned. There is no security response process, no PHP 8 support, no OpenAPI 3, and no community to answer questions. Do not introduce it into a new project. If you inherit it, budget for removal — the migration target is NelmioApiDocBundle directly (v4+), since the bundle adds little more than config defaults.

Version resolution will bite you first. The most common failure is Composer resolving a Nelmio version that conflicts with the bundle's constraints, or the bundle silently installing against a Symfony version it was never tested on. Pin both explicitly and run the test suite before trusting anything.

@ApiDoc vs @OA\* confusion. NelmioApiDocBundle v3 (the era this bundle targets) uses @ApiDoc. Nelmio v4 uses @OA\* from zircote/swagger-php. Every Stack Overflow answer you find will assume one or the other. Check which Nelmio actually resolved in composer.lock before copying any annotation from the internet.

Annotation parsing failures are silent. If @ApiDoc doesn't render, the cause is almost always (a) the annotation isn't imported (use Nelmio\ApiDocBundle\Annotation\ApiDoc;), (b) Doctrine's annotation autoload isn't configured for the bundle's namespace, or (c) the controller isn't reachable via the imported route. Clear the cache (rm -rf var/cache/*) after every annotation change — stale metadata is the #1 false alarm.

Entities as output= leak more than you expect. Pointing output at a Doctrine entity reflects all mapped fields, including internal IDs, soft-delete flags, and relations. Use explicit DTOs or @ApiDoc(output=...) with a dedicated serializer group. This is also a mild information-disclosure risk if the sandbox is ever exposed publicly.

Don't expose the sandbox in production. The bundle's defaults are dev-friendly, not prod-safe. The interactive UI reveals your entire route surface and lets anyone fire requests with your cookies. Gate it behind the dev firewall or an auth middleware, always.

Extension points, if you must customize. Override Nelmio's templates via Resources/views/ in your app bundle rather than editing vendor code; add custom handlers for auth headers or response envelopes via Nelmio's sanitize/documented_areas config. If you find yourself needing to fork kreta/simple-api-doc-bundle itself, that's the signal the wrapper has outlived its usefulness — take the config it ships and inline it into your own Nelmio setup.

Debugging order of operations. When docs look wrong: (1) confirm the route is registered, (2) confirm the controller action is annotated and imported, (3) check composer.lock for the Nelmio version, (4) clear cache, (5) run the dump command and read the JSON — the raw output tells you whether the problem is annotation parsing or template rendering. Steps 1–3 solve the overwhelming majority of issues without touching the bundle.