Api Doc Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nelmio/api-doc-bundle
   

   Ensure your config/bundles.php includes:

   Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true],
   

2. Enable Routes: Add to config/routes.yaml:

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

3. First Use Case: Annotate a controller method with #[OpenApi\Get]:

   use OpenApi\Attributes as OA;
   
   #[OA\Get(
       path: "/users",
       summary: "Get all users",
       responses: [
           new OA\Response(response: 200, description: "List of users")
       ]
   )]
   public function index(): array
   {
       return UserResource::collection(User::all());
   }
   

   Visit /api/doc to see the generated Swagger UI.

Implementation Patterns

Core Workflows

1. Attribute-Based Documentation: Use OpenAPI attributes (#[OA\Get], #[OA\RequestBody], etc.) directly on controllers, DTOs, and entities. Example for request body:

   #[OA\RequestBody(
       content: new OA\JsonContent(
           type: "array",
           items: new OA\Items(ref: "#/components/schemas/User")
       )
   )]
   

2. DTO Integration: Document request/response models using #[OA\Schema]:

   #[OA\Schema(
       schema: "User",
       type: "object",
       properties: [
           new OA\Property(property: "name", type: "string"),
           new OA\Property(property: "email", type: "string", format: "email")
       ]
   )]
   class UserResource extends Resource
   {
       // ...
   }
   

3. Route Grouping: Use #[OA\Tag] to group related endpoints:

   #[OA\Tag(name: "Users")]
   #[OA\Get(path: "/users/{id}")]
   public function show(User $user): UserResource
   {
       return new UserResource($user);
   }
   

4. Security Schemes: Define API keys or OAuth2 in config/packages/nelmio_api_doc.yaml:

   nelmio_api_doc:
       security_definitions:
           api_key: { type: "apiKey", in: "header", name: "X-API-KEY" }
   

5. Dynamic Documentation: Use #[OA\Operation] with operationId for dynamic route generation:

   #[OA\Operation(operationId: "createUser")]
   public function store(StoreUserRequest $request): UserResource
   {
       // ...
   }
   

Integration Tips

• Symfony Serializer: Ensure symfony/serializer is installed for DTO hydration.
• API Platform: Works seamlessly with @ApiResource; combine both bundles for enhanced docs.
• Custom Components: Extend OpenAPI schemas via nelmio_api_doc.components config:

  nelmio_api_doc:
      components:
          schemas:
              PaginatedResponse:
                  type: "object"
                  properties:
                      data: { type: "array" }
                      total: { type: "integer" }
  

Gotchas and Tips

Common Pitfalls

1. Attribute vs. Annotation: Nelmio 5.x requires PHP 8 attributes (not annotations). Update old @SWG\* to #[OA\*]:

   - @SWG\Get(...)
   + #[OA\Get(...)]
   

2. Type Resolution:

   • Symfony 6+: Use type_info: true in config for better type hints:

     nelmio_api_doc:
         type_info: true
     

   • Legacy Types: Avoid LegacyType (deprecated in 5.8+). Use Type from symfony/type-info.

3. Route Conflicts:

   • Ensure #[Route] and #[OA\*] paths match exactly. Use #[OA\Operation] for dynamic routes:

     #[OA\Operation(operationId: "deleteUser", summary: "Delete user")]
     #[Route('/users/{id}', methods: ['DELETE'])]
     

4. Swagger UI Issues:

   • Clear cache after config changes:

     php bin/console cache:clear
     

   • Dark mode fixes: Update to latest version (e.g., 5.9.1+).

5. File Uploads: Combine #[MapRequestPayload] and #[MapUploadedFile] carefully (fixed in 5.9.4):

   #[OA\RequestBody(
       content: new OA\MultipartContent(
           properties: [
               new OA\Property(property: "file", type: "string", format: "binary")
           ]
       )
   )]
   

Debugging Tips

• Validate OpenAPI: Use bin/console debug:nelmio-api-doc to inspect generated docs.
• Log Errors: Enable debug mode in nelmio_api_doc.yaml:

  nelmio_api_doc:
      debug: true
  

• Schema Conflicts: Use #[OA\Schema] with required: false for optional fields to avoid validation errors.

Extension Points

1. Custom Describers: Extend Nelmio\ApiDocBundle\Describer\DescriberInterface for custom type handling (e.g., Ulid support in 5.7.0).

2. Event Listeners: Subscribe to Nelmio\ApiDocBundle\Event\DocumentationCompleteEvent to modify the OpenAPI spec:

   use Nelmio\ApiDocBundle\Event\DocumentationCompleteEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class CustomDocSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               DocumentationCompleteEvent::NAME => 'onDocumentationComplete',
           ];
       }
   
       public function onDocumentationComplete(DocumentationCompleteEvent $event): void
       {
           $event->getDocument()->info->title = 'Custom API Title';
       }
   }
   

3. Swagger UI Customization: Override templates in templates/bundles/NelmioApiDoc/index.html.twig or use nelmio_api_doc.ui config:

   nelmio_api_doc:
       ui:
           title: "My API Docs"
           defaultModelsExpandDepth: -1