Documentation Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require api-platform/documentation
   

   Register the bundle in config/app.php under providers:

   ApiPlatform\Doctrine\Orm\Extension\DocumentationExtension::class,
   

2. First Use Case Enable OpenAPI/Swagger documentation in config/packages/api_platform.yaml:

   api_platform:
       formats:
           jsonld: ['application/ld+json']
           json: ['application/json']
           html: ['text/html']
       documentation:
           enabled: true
           api_keys:
               - { name: 'Authorization', type: 'header' }
   

   Access docs at /api/doc (or /api.jsonld for machine-readable format).

3. Where to Look First

   • Documentation Endpoint: /api/doc (interactive UI).
   • Source: src/Extension/DocumentationExtension.php (core logic).
   • Config: config/packages/api_platform.yaml (customization).

Implementation Patterns

Workflows

1. Generating Documentation

   • Automatic: Docs are auto-generated from API resources (entities with @ApiResource).
   • Manual Overrides: Use @ApiProperty/@ApiFilter annotations to customize schema.

     use ApiPlatform\Core\Annotation\ApiProperty;
     use ApiPlatform\Core\Annotation\ApiFilter;
     
     #[ApiResource]
     class Book {
         #[ApiProperty(description: "The book's title")]
         public string $title;
     
         #[ApiFilter(SearchFilter::class, properties: ["title"])]
         public string $author;
     }
     

2. Integration with Frontend

   • Serve /api.jsonld to frontend apps (e.g., React/Vue) for dynamic API exploration.
   • Embed Swagger UI in your app:

     <iframe src="/api/doc" width="100%" height="600px"></iframe>
     

3. Customizing Output

   • Themes: Extend Swagger UI via assets/swagger-ui/ or override templates in templates/bundles/apiplatform/documentation/.
   • Info Section: Customize API metadata in config/packages/api_platform.yaml:

     documentation:
         info:
             title: "My Awesome API"
             description: "Built with Laravel & API Platform"
     

4. Versioning

   • Use api_platform.version middleware to version endpoints (e.g., /api/v1/docs).

Best Practices

• Keep Annotations Clean: Avoid overloading entities with @ApiProperty if not needed.
• Leverage Events: Use ApiPlatform\EventListener\Event to modify docs dynamically (e.g., add auth schemes).
• Test Locally: Use php bin/console api:doc to generate docs without a full server.

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Docs may not update immediately after schema changes. Clear cache:

     php bin/console cache:clear
     

   • For production, disable cache in config/packages/api_platform.yaml during development:

     documentation:
         enabled: true
         cache: false
     

2. Annotation Conflicts

   • Symfony < 5.3: Use ApiPlatform\Core\Annotation (not ApiPlatform\Core\Bridge\Doctrine).
   • PHP 8 Attributes: Migrate to attributes (e.g., #[\ApiResource]) for future compatibility.

3. Missing Endpoints

   • If /api/doc returns 404, ensure:
     • The DocumentationExtension is registered.
     • No conflicting routes exist (e.g., custom doc route in routes/api.php).

4. Complex Relationships

   • Circular references in entities may break OpenAPI schema. Use @ApiResource with collectionOperations/itemOperations explicitly.

Debugging Tips

• Check Generated Schema: Visit /api.jsonld to inspect raw OpenAPI spec.
• Enable Verbose Logging:

  api_platform:
      documentation:
          debug: true
  

• Validate Annotations: Use php bin/console debug:container ApiPlatform\Metadata\Resource\Factory\ResourceMetadataFactory to verify resource metadata.

Extension Points

1. Custom Schemes Add OAuth2 or JWT support via documentation.api_keys:

   documentation:
       api_keys:
           - { name: "Authorization", type: "header", scheme: "bearer" }
   

2. Post-Processing Extend ApiPlatform\Metadata\Resource\Factory\ResourceMetadataFactoryDecorator to modify docs before generation.

3. Theming Override Swagger UI assets by publishing templates:

   php bin/console assets:install public
   

   Then customize public/swagger-ui/index.html.

4. Server-Side Rendering For Laravel Blade integration, use the api_platform.documentation service to generate HTML:

   $docs = $this->container->get('api_platform.documentation');
   echo $docs->getHtml();