Api Doc Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nelmio/api-doc-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+):

   return [
       // ...
       Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true],
   ];
   

2. Enable Annotations: Ensure your config/packages/nelmio_api_doc.yaml includes:

   nelmio_api_doc:
       documentation:
           info:
               title: 'Your API'
               description: 'API Documentation'
               version: '1.0.0'
   

3. First Use Case: Annotate a controller method to generate docs:

   use Nelmio\ApiDocBundle\Annotation\ApiDoc;
   
   class UserController extends Controller
   {
       /**
        * @ApiDoc(
        *     resource=true,
        *     description="Get a user by ID",
        *     requirements={
        *         {"name":"id", "dataType":"integer", "requirement":"\d+"}
        *     },
        *     statusCodes={
        *         200="Returned when successful",
        *         404="Returned when user not found"
        *     }
        * )
        */
       public function getUser(int $id): JsonResponse
       {
           // ...
       }
   }
   

   Access docs at /api/doc.

Implementation Patterns

Core Workflows

1. Annotation-Based Documentation:

   • Use @ApiDoc on controllers/methods for metadata (e.g., description, requirements, statusCodes).
   • Group endpoints with resource=true for logical sections in docs.

2. Request/Response Examples:

   /**
    * @ApiDoc(
    *     description="Create a user",
    *     input="Nelmio\ApiDocBundle\Annotation\ApiDoc::class",
    *     output={
    *         "class"="App\Entity\User",
    *         "groups"={"user"}
    *     }
    * )
    */
   

   • Leverage Symfony Serializer groups (@Groups) for response filtering.

3. Authentication:

   • Secure docs with nelmio_api_doc.security in config:

     nelmio_api_doc:
         documentation:
             securityDefinitions:
                 Bearer:
                     type: apiKey
                     in: header
                     name: Authorization
     

4. Swagger UI Customization:

   • Override templates in templates/NelmioApiDocBundle/ (e.g., default/index.html.twig).
   • Extend with JavaScript/CSS via assets/nelmio_api_doc/.

Integration Tips

• Symfony Flex: Use symfony/ux-swagger for modern UI (optional).
• API Platform: Works seamlessly with @ApiResource annotations.
• Testing: Mock docs in tests by overriding Nelmio\ApiDocBundle\Resolver\RouteResolver.

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Issue: Annotations ignored if annotations: true is missing in framework.yaml (Symfony <5.0).
   • Fix: Use framework: annotations: true or autoconfigure: true.

2. Route Conflicts:

   • Issue: /api/doc clashes with custom routes.
   • Fix: Configure a custom route path:

     nelmio_api_doc:
         documentation:
             routes:
                 path: /docs
     

3. Deprecated in Favor of OpenAPI:

   • Note: This bundle is unmaintained (last release 2019). Prefer nelmio/cors-bundle + zircote/swagger-php for new projects.

Debugging

• Enable Debug Mode:

  nelmio_api_doc:
      documentation:
          debug: true
  

  Logs route/annotation parsing issues to var/log/dev.log.

• Validate Annotations: Use php bin/console debug:container --parameter=nelmio_api_doc.documentation to check loaded docs.

Extension Points

1. Custom Annotations: Extend Nelmio\ApiDocBundle\Annotation\ApiDoc via traits or new annotations (requires bundle overrides).

2. Dynamic Documentation: Override Nelmio\ApiDocBundle\Resolver\RouteResolver to inject runtime data (e.g., auth tokens).

3. Non-Controller Docs: Use Nelmio\ApiDocBundle\Annotation\ApiDoc on services with @Route via nelmio_api_doc.route config:

   nelmio_api_doc:
       routes:
           - { resource: "App\Service\CustomApi", type: "annotation" }