Api Doc Bundle Laravel Package

## Getting Started

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

Ensure your AppKernel.php (or config/bundles.php for Symfony 4+) includes:

new Appstone\ApiDocBundle\ApiDocBundle(),

2. Enable Annotations: Add this to your config/packages/nelmio_api_doc.yaml (create if missing):

   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",
        *     statusCodes={200="Returns user data"}
        * )
        */
       public function getUserAction()
       {
           return $this->json(['id' => 1, 'name' => 'John']);
       }
   }
   

4. Access Docs: Visit /doc (default route) to see the generated Swagger UI.

Implementation Patterns

Common Workflows

1. Controller Annotations: Use @ApiDoc on methods to define endpoints:

   /**
    * @ApiDoc(
    *     resource=true,
    *     description="Create a user",
    *     input="App\Entity\User",
    *     statusCodes={
    *         201="User created",
    *         400="Invalid input"
    *     }
    * )
    */
   public function postUserAction(Request $request)
   {
       // ...
   }
   

2. Request/Response Models: Define models in YAML (e.g., config/api_doc/models/user.yml):

   User:
       properties:
           id:
               type: integer
               description: User ID
           name:
               type: string
               description: User name
   

3. Grouping Routes: Use groups in annotations to organize endpoints:

   /**
    * @ApiDoc(
    *     resource=true,
    *     description="User operations",
    *     groups={"users"}
    * )
    */
   

4. Authentication: Configure security in nelmio_api_doc.yaml:

   nelmio_api_doc:
       areas:
           path_patterns:
               - ^/api(?!/doc$)  # Exclude doc route
       securityDefinitions:
           api_key:
               type: apiKey
               in: header
               name: X-API-KEY
   

5. Dynamic Documentation: Extend the bundle with custom annotations or services:

   // src/Service/CustomDocBuilder.php
   class CustomDocBuilder extends AbstractDocBuilder
   {
       public function build()
       {
           // Add custom logic
       }
   }
   

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Ensure annotations: true is set in config/packages/framework.yaml:

     framework:
         annotations: true
     

   • If using PHP 7.4+, enable attributes: true and migrate to attributes (e.g., #[\Nelmio\ApiDoc\Annotation\ApiDoc(...)]).

2. Route Conflicts:

   • The /doc route may conflict with existing routes. Customize the route in nelmio_api_doc.yaml:

     nelmio_api_doc:
         routes:
             default:
                 path: /api-docs
     

3. Caching Issues:

   • Clear cache after adding new annotations:

     php bin/console cache:clear
     

4. Symfony 4+ Compatibility:

   • The bundle targets Symfony 2.3–3.0. For Symfony 4/5, use nelmio/api-doc-bundle (the original package) instead, as this fork (appstone/api-doc-bundle) lacks maintenance.

5. Missing Dependencies:

   • The require-dev section lists optional bundles (e.g., friendsofsymfony/rest-bundle). Install them if you need advanced features like request/response validation.

Debugging Tips

1. Check Generated JSON: Visit /doc/json to inspect the raw OpenAPI spec. Validate it using Swagger Editor.

2. Enable Debug Mode: Set debug: true in nelmio_api_doc.yaml to log issues:

   nelmio_api_doc:
       debug: true
   

3. Common Errors:

   • "No routes found": Ensure your controller routes are annotated or loaded via nelmio_api_doc.routes config.
   • Annotation not recognized: Verify the use statement (use Nelmio\ApiDocBundle\Annotation\ApiDoc).

Extension Points

1. Custom Templates: Override Twig templates in templates/NelmioApiDocBundle/ to modify the UI.

2. Event Listeners: Subscribe to NelmioApiDocBundle.EventListener events to modify docs dynamically:

   // src/EventListener/CustomDocListener.php
   class CustomDocListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               NelmioApiDocBundle::DOCUMENTATION_BUILD => 'onDocumentationBuild',
           ];
       }
   
       public function onDocumentationBuild(DocumentationEvent $event)
       {
           $event->getDocumentation()->setInfo('custom', 'value');
       }
   }
   

3. Integrate with API Platform: If using api-platform/core, combine with nelmio/api-doc-bundle for seamless OpenAPI generation.

4. Localization: Extend the bundle to support multi-language docs by overriding the Twig translations in translations/.

---
**Note**: This assessment assumes the package is a fork of `nelmio/api-doc-bundle` with minor changes. For production use, prefer the original [`nelmio/api-doc-bundle`](https://github.com/nelmio/NelmioApiDocBundle), which is actively maintained. The `appstone` fork appears abandoned (0 stars, no commits). Always verify compatibility with your Symfony version.