Blueprint Laravel Package

Getting Started

First Steps

1. Installation

   composer require dingo/blueprint
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Dingo\Blueprint\BlueprintServiceProvider::class,
   ],
   

2. Basic Setup Register the blueprint in your routes/api.php:

   $api = app('Dingo\Api\Routing\Router');
   $api->version('v1', function ($api) {
       $api->blueprint('api-blueprint.apib');
   });
   

3. First Use Case Define a simple route and let the package auto-generate API Blueprint:

   $api->get('users', 'App\Http\Controllers\UserController@index');
   

   Run the generator:

   php artisan blueprint:generate
   

   Check storage/api-blueprint.apib for the output.

Implementation Patterns

Core Workflows

1. Route-Based Documentation

   • Annotate controllers with @api tags for metadata:

     /**
      * @api {get} /users Retrieve all users
      * @apiName GetUsers
      * @apiGroup Users
      */
     public function index() { ... }
     

   • Use blueprint:generate to sync routes with the .apib file.

2. Dynamic Blueprint Generation

   • Integrate with Laravel’s route model binding:

     $api->get('users/{id}', 'UserController@show')
         ->where('id', '[0-9]+');
     

     The package auto-infers parameter types (e.g., id as integer).

3. Customizing Output

   • Override the default template by publishing assets:

     php artisan vendor:publish --tag=blueprint-views
     

   • Extend the BlueprintGenerator class to modify rendering logic.

4. API Versioning

   • Generate separate blueprints per version:

     $api->version('v1', function ($api) {
         $api->blueprint('v1.apib');
     });
     $api->version('v2', function ($api) {
         $api->blueprint('v2.apib');
     });
     

Integration Tips

• Laravel Scout: Document search endpoints with @apiParam {String} query for clarity.
• Validation Rules: Use @apiParam {String} [name] to mirror Laravel’s FormRequest rules.
• Testing: Pair with Pest/Laravel’s HTTP tests to ensure docs match implementation:

  test('GET /users generates correct blueprint')
      ->getJson('/api/v1/users')
      ->assertOk();
  

Gotchas and Tips

Pitfalls

1. Route Caching Conflicts

   • Clear route cache after adding new routes:

     php artisan route:clear
     php artisan blueprint:generate
     

   • Symptom: Missing routes in .apib despite recent changes.

2. Middleware Misrepresentation

   • Blueprint ignores middleware by default. Explicitly document auth/rate-limiting:

     /**
      * @api {get} /admin/users Requires admin role
      * @apiHeader {String} Authorization Bearer token
      */
     

3. Nested Resources

   • Avoid ambiguous paths like /users/{user}/posts/{post}—use explicit namespacing:

     $api->get('users/{user}/posts/{post}', 'PostController@show')
         ->name('users.posts.show');
     

Debugging

• Verbose Output: Enable debug mode in config/blueprint.php:

  'debug' => env('BLUEPRINT_DEBUG', false),
  

  Logs generated blueprint steps to storage/logs/blueprint.log.

• Partial Generates: Use --force to overwrite partial files:

  php artisan blueprint:generate --force
  

Extension Points

1. Custom Attributes Override BlueprintGenerator to add custom annotations:

   // app/Extensions/CustomBlueprintGenerator.php
   class CustomBlueprintGenerator extends BlueprintGenerator {
       protected function parseAnnotations($method) {
           // Add logic for @apiExample tags
       }
   }
   

   Register in BlueprintServiceProvider:

   $this->app->bind('blueprint.generator', function () {
       return new CustomBlueprintGenerator();
   });
   

2. Post-Processing Hook into blueprint.generated event to modify the .apib file:

   // In a service provider
   event(new BlueprintGenerated($blueprintPath));
   

3. Non-Route Resources Document non-route assets (e.g., WebSocket events) by extending the Blueprint class:

   $blueprint->addResource('WebSocket', [
       'events' => [
           'chat.message' => ['description' => 'Broadcast a chat message']
       ]
   ]);