## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require nelmio/api-doc-bundle

Ensure NelmioApiDocBundle is enabled in config/bundles.php:

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

Basic Configuration: Add to config/packages/nelmio_api_doc.yaml:

nelmio_api_doc:
    documentation:
        info:
            title: "My API"
            description: "API Documentation"
            version: "1.0.0"
        components:
            securitySchemes:
                bearerAuth:
                    type: http
                    scheme: bearer
                    bearerFormat: JWT
        security:
            - bearerAuth: []

First Use Case: Annotate a controller method to generate API docs:

use Nelmio\ApiDocBundle\Annotation\ApiDoc;

class UserController extends AbstractController
{
    /**
     * @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: Visit /api/doc (default route) to see the generated Swagger/OpenAPI UI.

Implementation Patterns

Controller Annotations

Resource Endpoints: Use @ApiDoc(resource=true) for RESTful endpoints. Automatically generates:
- Path, HTTP methods, and parameters.
- Request/response examples (if using @ApiDoc with examples).
```
/**
 * @ApiDoc(
 *     resource=true,
 *     description="Create a new user",
 *     input="App\\Dto\\CreateUserDto",
 *     output="App\\Dto\\UserDto"
 * )
 */
```

Parameter Documentation: Document query, path, and body parameters:

/**
 * @ApiDoc(
 *     parameters={
 *         {"name":"page", "dataType":"integer", "required":false, "description":"Page number"},
 *         {"name":"limit", "dataType":"integer", "required":false, "description":"Items per page"}
 *     }
 * )
 */

Authentication: Link security schemes to endpoints:

/**
 * @ApiDoc(
 *     security={"bearerAuth":{}},
 *     description="Protected endpoint"
 * )
 */

Integration with Laravel-Specific Features

Route Groups: Apply @ApiDoc at the route group level (via Route::group with middleware):

Route::prefix('api/v1')->group(function () {
    Route::get('/users', [UserController::class, 'index'])
        ->middleware('auth:api')
        ->name('users.index');
});

Configure global security in nelmio_api_doc.yaml to reflect this.

Form Request Validation: Use @ApiDoc(input="App\\Http\\Requests\\StoreUserRequest") to auto-generate docs from validation rules:
```
/**
 * @ApiDoc(
 *     input="App\\Http\\Requests\\StoreUserRequest",
 *     description="Store a new user"
 * )
 */
```
API Resources: For Laravel API Resources, use @ApiDoc(output="App\\Http\\Resources\\UserResource") to document serialized responses.

Dynamic Documentation

Conditional Routes: Use nelmio_api_doc.route_version to version your API docs:
```
nelmio_api_doc:
    routes:
        version: v1
```
Override dynamically in controllers:
```
/**
 * @ApiDoc(routeVersion="v2")
 */
```
Event-Driven Updates: Trigger doc regeneration after deployments or schema changes:
```
php bin/console nelmio:api-doc:generate
```

Gotchas and Tips

Common Pitfalls

Annotation Parsing Issues:
- Ensure doctrine/annotations is installed and configured in composer.json.
- Clear cache after adding new annotations:
```
php artisan cache:clear
php artisan config:clear
```
Route Mismatches:
- Nelmio uses Symfony’s router. If routes don’t appear:
  - Verify routes are loaded in routes/api.php (not web.php).
  - Check for conflicting route priorities (e.g., Route::prefix vs. Route::name).
Circular References:
- Avoid circular references in @ApiDoc(input/output) (e.g., UserDto referencing ProfileDto which references UserDto). Use nullable: true or simplify DTOs.
OpenAPI 3.0 vs. Swagger 2.0:
- Version 4.0 defaults to OpenAPI 3.0. For Swagger 2.0, use version 3.x:
```
composer require nelmio/api-doc-bundle:3.x
```

Debugging Tips

Inspect Generated Docs: Access raw JSON at /api/doc.json to debug missing/incorrect entries.
Enable Verbose Logging: Add to nelmio_api_doc.yaml:
```
nelmio_api_doc:
    debug: true
```
Check logs for annotation parsing errors.
Validate Annotations: Use PHPStorm’s "Inspect Code" or phpstan to catch syntax errors in annotations.

Advanced Configuration

Custom Templates: Override the Swagger UI template by copying vendor/nelmio/api-doc-bundle/Resources/views to templates/nelmio_api_doc and modifying.

Authentication Plugins: Extend security schemes dynamically:

nelmio_api_doc:
    components:
        securitySchemes:
            apiKeyAuth:
                type: apiKey
                in: header
                name: X-API-KEY

Performance: Cache generated docs in production:

nelmio_api_doc:
    cache:
        enabled: true
        dir: "%kernel.cache_dir%/nelmio_api_doc"

Extension Points

Custom Annotations: Extend Nelmio’s annotation parser by implementing Nelmio\ApiDocBundle\Parser\ParserInterface.

Post-Processing: Modify the generated OpenAPI spec via an event subscriber:

use Nelmio\ApiDocBundle\Event\AfterGenerateEvent;

public function onAfterGenerate(AfterGenerateEvent $event)
{
    $event->getDocument()->info->title = 'Custom Title';
}

services:
    App\EventListener\ApiDocSubscriber:
        tags:
            - { name: kernel.event_subscriber }

Testing: Mock Nelmio in PHPUnit:

$this->get('/api/doc.json')->assertJsonStructure([
    'openapi', 'info', 'paths' => [
        '/*' => ['get' => ['tags', 'parameters', 'responses']]
    ]
]);


```markdown
## Laravel-Specific Adjustments
### Route Configuration
Nelmio relies on Symfony’s router. For Laravel, ensure:
1. **Route Prefixes**:
   Prefix API routes in `routes/api.php` to avoid conflicts:
   ```php
   Route::prefix('api')->group(function () {
       Route::get('/users', [UserController::class, 'index']);
   });

Route Naming: Use named routes for clarity in docs:

Route::get('/users/{id}', [UserController::class, 'show'])
    ->name('users.show');

Reference names in @ApiDoc:

/**
 * @ApiDoc(resource=true, routeName="users.show")
 */

Artisan Commands

Leverage Nelmio’s CLI tools in Laravel:

Generate Docs:
```
php artisan nelmio:api-doc:generate
```
Serve Docs Locally:
```
php artisan nelmio:api-doc:serve
```

Integration with Laravel Features

Middleware: Document middleware requirements:

/**
 * @ApiDoc(
 *     security={"bearerAuth":{}},
 *     description="Requires auth middleware"
 * )
 */
public function sensitiveAction()
{
    // ...
}

API Resources: Use @ApiDoc(output="App\\Http\\Resources\\UserResource") to document serialized responses:

Api Doc Bundle Laravel Package