Laravel Openapi Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-openapi-cli
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\OpenApiCli\OpenApiCliServiceProvider"
   

2. Define a Command: Create a new Artisan command that extends Spatie\OpenApiCli\OpenApiCommand:

   php artisan make:command GenerateApiDocs
   

   Update the generated file:

   <?php
   namespace App\Console\Commands;
   
   use Spatie\OpenApiCli\OpenApiCommand;
   
   class GenerateApiDocs extends OpenApiCommand
   {
       protected $signature = 'api:docs {--spec= : Path to OpenAPI spec file}';
       protected $description = 'Generate API documentation from OpenAPI spec';
   }
   

3. First Use Case: Run the command with your OpenAPI spec file:

   php artisan api:docs --spec=path/to/api-spec.yaml
   

   This will generate a CLI output or file based on your spec.

Where to Look First

• Config File: config/openapi-cli.php (if published) for customizing output paths, formats, or behavior.
• Command Class: Spatie\OpenApiCli\OpenApiCommand for extending functionality.
• Examples: Check the GitHub repo for sample specs and commands.

Implementation Patterns

Workflows

1. Integrate with CI/CD: Add the command to your deployment pipeline to auto-generate API docs on every push:

   # .github/workflows/docs.yml
   jobs:
     generate-docs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-php@v2
         - run: composer install
         - run: php artisan api:docs --spec=api-spec.yaml --output=docs/openapi.json
   

2. Dynamic Spec Loading: Load OpenAPI specs from multiple files or directories:

   // In your command class
   public function handle()
   {
       $specs = [
           'path/to/spec1.yaml',
           'path/to/spec2.yaml',
       ];
   
       foreach ($specs as $spec) {
           $this->generateFromSpec($spec);
       }
   }
   

3. Custom Output Formats: Extend the command to output to Markdown, HTML, or other formats:

   use Spatie\OpenApiCli\OpenApiCommand;
   
   class GenerateMarkdownDocs extends OpenApiCommand
   {
       protected function generateOutput($spec)
       {
           // Custom logic to convert OpenAPI to Markdown
           file_put_contents('docs/api.md', $this->convertToMarkdown($spec));
       }
   }
   

Integration Tips

1. Pair with Laravel API Resources: Use the generated docs to validate your API responses:

   // In your API resource
   public function toArray($request)
   {
       // Ensure response matches OpenAPI schema
       return [
           'data' => $this->formatData(),
           'meta' => ['schema' => 'UserSchema'], // Reference OpenAPI schema
       ];
   }
   

2. Document Package APIs: If developing a Laravel package, use this to document its API endpoints:

   // In your package's command
   class PackageApiDocs extends OpenApiCommand
   {
       protected $signature = 'package:docs {--package= : Package name}';
       protected function getSpecPath()
       {
           return base_path("packages/{$this->option('package')}/api-spec.yaml");
       }
   }
   

3. Versioned APIs: Generate docs for multiple API versions:

   php artisan api:docs --spec=v1/api-spec.yaml --output=docs/v1
   php artisan api:docs --spec=v2/api-spec.yaml --output=docs/v2
   

Gotchas and Tips

Pitfalls

1. Spec File Paths:

   • Issue: Hardcoding paths in commands may break in shared environments.
   • Fix: Use Laravel's base_path() or storage_path():

     $specPath = base_path('api-spec.yaml');
     

2. Schema Validation:

   • Issue: Invalid OpenAPI specs may cause silent failures.
   • Fix: Validate specs before processing:

     use Spatie\OpenApiCli\OpenApiValidator;
     
     if (!OpenApiValidator::validate($specPath)) {
         $this->error('Invalid OpenAPI spec!');
         return 1;
     }
     

3. Output Overwriting:

   • Issue: Running commands multiple times may overwrite files.
   • Fix: Use --force flag or append timestamps to output files:

     $outputPath = "docs/openapi-{$this->getTimestamp()}.json";
     

Debugging

1. Verbose Mode: Enable debug output for troubleshooting:

   php artisan api:docs --spec=api-spec.yaml --verbose
   

2. Log Spec Parsing: Log the parsed OpenAPI object for debugging:

   $spec = $this->parseSpec($specPath);
   \Log::debug('Parsed spec:', ['spec' => $spec]);
   

Extension Points

1. Custom Parsers: Extend Spatie\OpenApiCli\Parsers\OpenApiParser to support additional spec formats:

   class CustomParser extends OpenApiParser
   {
       public function parse($specPath)
       {
           // Custom parsing logic
           return $this->transformToStandardFormat($rawSpec);
       }
   }
   

2. Hooks for Post-Processing: Override generateOutput() to add metadata or transform data:

   protected function generateOutput($spec)
   {
       $output = $this->convertToJson($spec);
       $output['generated_at'] = now()->toIso8601String();
       file_put_contents($this->outputPath, $output);
   }
   

3. Event Listeners: Dispatch events for pre/post-processing:

   use Spatie\OpenApiCli\Events\SpecProcessed;
   
   protected function handle()
   {
       $spec = $this->parseSpec($this->option('spec'));
       event(new SpecProcessed($spec));
       $this->generateOutput($spec);
   }
   

Config Quirks

1. Default Output Path: The default output path is storage/app/openapi.json. Override in config/openapi-cli.php:

   'output_path' => storage_path('custom/openapi-docs'),
   

2. Spec File Extensions: The package defaults to .yaml and .json. Add support for .yml or .openapi in config:

   'supported_extensions' => ['yaml', 'yml', 'json', 'openapi'],
   

3. Environment-Specific Specs: Use Laravel's environment files to switch specs:

   // In your command
   $specPath = config('openapi.spec_path', base_path('api-spec.yaml'));