Api Doc Property Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dawen/api-doc-property-bundle
   

   Register the bundle in config/bundles.php (Laravel) or AppKernel.php (Symfony):

   Dawen\Bundle\ApiDocPropertyBundle\ApiDocPropertyBundle::class => ['all' => true],
   

2. First Use Case: Add the @ApiDocProperty annotation to a property in your Symfony Controller/Entity to expose it in NelmioApiDoc:

   use Dawen\Bundle\ApiDocPropertyBundle\Annotation\ApiDocProperty;
   
   /**
    * @ApiDocProperty(type="string", description="User's full name")
    */
   private $fullName;
   

3. Verify Integration: Ensure NelmioApiDoc is configured and running (e.g., via nelmio_api_doc:debug). Check the generated API docs (e.g., /api/doc) to confirm the property appears.

Implementation Patterns

Common Workflows

1. Documenting Custom Properties: Use @ApiDocProperty for properties not covered by JMS Serializer, Symfony Validator, or JSON:

   /**
    * @ApiDocProperty(
    *     type="array<string>",
    *     description="List of user roles",
    *     name="roles"
    * )
    */
   private $customRoles;
   

2. Integration with NelmioApiDoc:

   • Ensure NelmioApiDoc’s NelmioApiDocBundle is installed and configured.
   • The bundle extends Nelmio’s parser, so no additional routes or middleware are needed.

3. Laravel-Specific Setup:

   • For Laravel, use spatie/laravel-package-tools to auto-register the bundle in config/app.php:

     'providers' => [
         Dawen\Bundle\ApiDocPropertyBundle\ApiDocPropertyServiceProvider::class,
     ],
     

   • Publish config (if available) with:

     php artisan vendor:publish --provider="Dawen\Bundle\ApiDocPropertyBundle\ApiDocPropertyServiceProvider"
     

4. Dynamic Property Documentation: Use the name attribute to override the property name in docs:

   /**
    * @ApiDocProperty(type="integer", name="user_id")
    */
   private $id; // Documented as "user_id" in API docs
   

Integration Tips

• Combine with JMS Serializer: Use @ApiDocProperty for metadata while letting JMS handle serialization.
• Validation: Pair with Symfony Validator for runtime validation:

  /**
   * @ApiDocProperty(type="string", description="Email address")
   * @Assert\Email()
   */
  private $email;
  

• API Groups: Use Nelmio’s @ApiDoc annotations to group documented properties logically.

Gotchas and Tips

Pitfalls

1. Annotation Parsing Order:

   • The bundle relies on Nelmio’s parser. If properties aren’t appearing, ensure:
     • NelmioApiDoc’s parser config includes the bundle’s parser (check config/nelmio_api_doc.yaml).
     • The @ApiDocProperty annotation is placed above the property (not in PHPDoc block for some parsers).

2. Type System Quirks:

   • The type attribute is not validated—incorrect types (e.g., "foobar") will appear as-is in docs. Use standard PHP types (e.g., "string", "array<int>") for consistency.
   • For complex types, use fully qualified class names:

     @ApiDocProperty(type="App\Entity\User[]")
     

3. Laravel-Specific Issues:

   • If using Laravel, ensure the bundle’s service provider is loaded after NelmioApiDoc’s provider.
   • Clear cache after installation:

     php artisan config:clear && php artisan cache:clear
     

4. Overriding Default Behavior:

   • The bundle does not modify serialization behavior—it only adds metadata to NelmioApiDoc. Use @Groups (from API Platform) or JMS @SerializedName for runtime changes.

Debugging

• Check Parsed Annotations: Use Nelmio’s debug command to inspect parsed properties:

  php bin/console nelmio_api_doc:debug
  

  Look for your @ApiDocProperty entries under the "properties" section.

• Log Parser Events: Enable debug mode in nelmio_api_doc.yaml:

  parser:
      debug: true
  

  Check logs for parsing errors (e.g., monolog logs).

Extension Points

1. Custom Property Types: Extend the bundle by creating a custom parser for @ApiDocProperty. Override the Dawen\Bundle\ApiDocPropertyBundle\Parser\ApiDocPropertyParser class and register it in Nelmio’s parser chain.

2. Dynamic Property Generation: Use the bundle’s ApiDocPropertyExtension to add properties programmatically (e.g., from database metadata):

   $extension = new ApiDocPropertyExtension();
   $extension->addProperty($entity, 'dynamic_field', 'string', 'Generated dynamically');
   

3. Integration with API Platform: Combine with api-platform/core for automatic doc generation:

   # config/packages/api_platform.yaml
   api_platform:
       formats:
           jsonld:
               mime_types: ['application/ld+json']
       patch_formats:
           json: true
       swagger:
           versions: [3]