Api Doc Bundle Laravel Package

Integration Approach

Stack Fit

• Laravel Compatibility: The oro/api-doc-bundle (NelmioApiDocBundle fork) is Symfony-centric, requiring a hybrid integration approach for Laravel. Key considerations:

  • Symfony Components: Leverage symfony/serializer, symfony/http-kernel, and symfony/dependency-injection as drop-in replacements where possible.
  • Annotation Support: Use spatie/laravel-annotation-reader to parse @ApiDoc annotations (Laravel lacks native support).
  • Routing: Generate OpenAPI specs from Laravel’s route definitions (e.g., Route::getRoutes()) instead of Symfony’s router.
  • Middleware/Events: Replace Symfony’s kernel events with Laravel’s Events facade or custom middleware.

  Recommended Stack:

  Laravel Feature	Integration Strategy	Tools/Libraries
  Routing	Parse Laravel routes → adapt to OpenAPI spec	spatie/laravel-openapi (partial)
  Annotations	Custom parser or spatie/laravel-annotation-reader	doctrine/annotations (fallback)
  Serialization	symfony/serializer or spatie/array-to-xml	jms/serializer (legacy)
  Dependency Injection	Laravel’s container or PHP-DI	php-di/php-di
  HTTP Layer	Symfony’s HttpFoundation via symfony/http-foundation	symfony/http-kernel (for kernel events)

• Avoid:

  • Full Symfony kernel integration (high maintenance).
  • Direct NelmioApiDocBundle usage without abstraction (Symfony lock-in).

Migration Path

1. Phase 1: Assessment (1–2 weeks)

   • Audit Existing Docs: Inventory current API documentation (e.g., Swagger YAML, Postman collections, or manual Markdown).
   • Benchmark Tools: Compare oro/api-doc-bundle against Laravel-native alternatives:
     • darkajp/l5-swagger (Laravel 5/6/7/8).
     • zircote/swagger-php (pure PHP, annotation-based).
     • spatie/laravel-openapi (modern, annotation-driven).
   • Decision Point: If oro/api-doc-bundle offers unique features (e.g., advanced Symfony annotation support), proceed; otherwise, favor Laravel-native tools.

2. Phase 2: Proof of Concept (2–3 weeks)

   • Isolate Core Logic: Extract the bundle’s OpenAPI generation logic (e.g., NelmioApiDocBundle/Generator/OpenApiGenerator) into a standalone PHP library.
   • Laravel Adapter:
     • Create a service to convert Laravel routes to Symfony’s RouteCollection format.
     • Mock Symfony dependencies (e.g., ContainerInterface, EventDispatcher) using Laravel’s equivalents.
   • Example Adapter:

     // app/Services/OpenApiAdapter.php
     use Symfony\Component\Routing\RouteCollection;
     use Illuminate\Support\Facades\Route;
     
     class OpenApiAdapter
     {
         public function getRouteCollection(): RouteCollection
         {
             $collection = new RouteCollection();
             foreach (Route::getRoutes() as $route) {
                 $symfonyRoute = new \Symfony\Component\Routing\Route(
                     $route->uri(),
                     $route->methods(),
                     $route->getAction()['uses']
                 );
                 $collection->add($route->getName(), $symfonyRoute);
             }
             return $collection;
         }
     }
     

   • Test: Generate OpenAPI specs for 1–2 controllers and validate against manual specs.

3. Phase 3: Full Integration (3–4 weeks)

   • Bundle Wrapper: Create a Laravel package (e.g., laravel-nelmio-api-doc) to wrap the bundle’s logic:
     • Composer package with Laravel service provider.
     • Configuration published via publishes (e.g., config/nelmio_api_doc.php).
     • Artisan command to regenerate docs (e.g., php artisan api:docs).
   • Annotation Support:
     • Use spatie/laravel-annotation-reader to parse @ApiDoc:

       $reader = new \Spatie\LaravelAnnotationReader\AnnotationReader();
       $annotations = $reader->getMethodAnnotations(new \ReflectionMethod(UserController::class, 'show'));
       

   • Swagger UI:
     • Serve the generated OpenAPI JSON via a Laravel route:

       Route::get('/api/doc.json', [OpenApiController::class, 'getJson']);
       

     • Integrate with darkajp/l5-swagger for UI or use a standalone Swagger UI instance.

4. Phase 4: CI/CD & Validation (1–2 weeks)

   • Automated Validation:
     • Add a GitHub Action to validate OpenAPI specs using swagger-cli:

       # .github/workflows/api-docs.yml
       - name: Validate API Docs
         run: |
           composer require swagger-api/swagger-cli
           vendor/bin/swagger-cli validate ./storage/api-doc.json
       

   • Cache Generated Docs:
     • Store OpenAPI JSON in storage/api-doc.json and cache with laravel-cache:

       Cache::remember('api-docs', now()->addHours(1), function () {
           return $this->generateOpenApi();
       });
       

Compatibility

• Laravel Versions: Tested on Laravel 8+ (Symfony 5+ compatibility). For Laravel 7, use symfony/http-client v4.
• PHP Versions: Requires PHP 7.4+ (Symfony 5’s minimum).
• Dependencies:
  • Conflicts: Avoid mixing nelmio/api-doc-bundle and oro/api-doc-bundle (use only the fork).
  • Symfony Components: Prefer symfony/* packages (e.g., symfony/serializer) over jms/serializer for consistency.

Sequencing

1. Start Small: Document a single API module (e.g., /api/v1/users) before scaling.
2. Prioritize Critical Endpoints: Focus on endpoints used by partners or public clients first.
3. Iterate on Annotations: Begin with @ApiDoc(resource=true) for resources, then add @ApiDoc(description=...) for methods.
4. UI Last: Implement Swagger UI only after OpenAPI JSON generation is stable.

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor oro/api-doc-bundle for updates (low activity; prefer upstream nelmio/api-doc-bundle v3.x if available).
  • Strategy: Pin versions in composer.json and backport critical fixes manually.
• Laravel-Specific Maintenance:
  • Adapter Layer: The custom OpenApiAdapter and annotation parser will require updates if Laravel’s routing or annotation systems change.
  • Dependency Management: Track Symfony component versions (e.g., symfony/serializer) for breaking changes.
• Documentation:
  • Maintain a docs/API_DOCS.md with:
    • Annotation usage examples.
    • Troubleshooting (e.g., "Why are my annotations ignored?").
    • CI/CD validation steps.

Support

• Developer Onboarding:
  • Training: 1-hour session on:
    • Adding @ApiDoc annotations.
    • Regenerating docs (php artisan api:docs).
    • Debugging missing endpoints (e.g., checking route registration).
  • Cheat Sheet:

    ## Common Annotations
    - `@ApiDoc(resource=true)`: Marks a resource (e.g., `/users`).
    - `@ApiDoc(description="...")`: Adds method-level docs.
    - `@ApiDoc(
        parameters={
            @ApiDocParameter(name="id", description="User ID", required=true)
        }
      )`: Documents parameters.
    

• Support Channels:
  • Symfony Issues: Redirect to nelmio/api-doc-bundle GitHub for core bugs.
  • Laravel Issues: Use the project’s GitHub issues or create a laravel-nelmio-api-doc repo.
• SLA:
  • P1: Missing critical endpoint docs (blocking API releases).
  • P2: Annotation parsing errors (e.g., invalid syntax).
  • P3: Swagger UI styling issues (low priority).

Scaling

• Performance:
  • Generation: OpenAPI generation is O(n) (where n = number of routes). For 1,000+ endpoints, cache the output:

    Cache::forever('api-docs', $this->generateOpenApi());
    

  • Swagger UI: Offload to a CDN or static site generator (e.g., generate HTML at build time).
• Large APIs:
  • Split Documentation: Use `nel