Dokapi Rest Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dokapi/dokapi-rest
   

   Add the service provider to config/app.php under providers:

   Dokapi\Rest\RestServiceProvider::class,
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Dokapi\Rest\RestServiceProvider"
   

   Update config/dokapi.php with your API base URL and namespace.

3. First Use Case Annotate a controller method to generate documentation:

   use Dokapi\Rest\Annotations\Api;
   
   class UserController extends Controller
   {
       /**
        * @Api(
        *     path="/users",
        *     method="GET",
        *     description="Get all users",
        *     response={"200": {"type": "array", "items": {"$ref": "#/definitions/User"}}}
        * )
        */
       public function index()
       {
           return User::all();
       }
   }
   

4. Generate Documentation Run the generator:

   php artisan dokapi:generate
   

   Outputs OpenAPI/Swagger-compliant JSON/YAML to storage/dokapi.

Implementation Patterns

Controller Annotations

• Standardize Annotations Use consistent annotation formats across controllers:

  /**
   * @Api(
   *     path="/users/{id}",
   *     method="GET",
   *     description="Fetch a user by ID",
   *     parameters={
   *         {"name": "id", "in": "path", "type": "integer", "required": true}
   *     },
   *     response={"200": {"$ref": "#/definitions/User"}}
   * )
   */
  

• Group Related Endpoints Use @ApiGroup at the class level for logical grouping:

  /**
   * @ApiGroup(
   *     name="Users",
   *     description="User management endpoints"
   * )
   */
  class UserController extends Controller { ... }
  

Integration with Laravel Features

• Middleware & Auth Document auth requirements via @ApiSecurity:

  /**
   * @ApiSecurity("bearerAuth")
   */
  public function sensitiveData() { ... }
  

• Form Request Validation Auto-generate parameter schemas from FormRequest classes:

  use Dokapi\Rest\Annotations\ApiRequest;
  
  /**
   * @ApiRequest(StoreUserRequest::class)
   */
  public function store(StoreUserRequest $request) { ... }
  

Workflows

1. Iterative Documentation

   • Add annotations incrementally alongside development.
   • Regenerate docs with php artisan dokapi:generate after each change.

2. CI/CD Pipeline

   • Integrate dokapi:generate into your build process to ensure docs stay updated.
   • Example .github/workflows/docs.yml:

     - name: Generate API Docs
       run: php artisan dokapi:generate
     - name: Upload Artifact
       uses: actions/upload-artifact@v2
       with:
         name: api-docs
         path: storage/dokapi
     

3. Versioning

   • Use --version flag to generate docs for specific API versions:

     php artisan dokapi:generate --version=v1
     

   • Store outputs in versioned directories (e.g., storage/dokapi/v1, storage/dokapi/v2).

Gotchas and Tips

Pitfalls

• Annotation Parsing Errors

  • Symptom: Generator fails with Invalid annotation syntax.
  • Fix: Validate annotations using PHPStan or php artisan dokapi:validate.
  • Tip: Use tools like PHP Annotations for syntax checking.

• Circular References

  • Symptom: $ref loops cause infinite recursion in generated docs.
  • Fix: Use inline schemas for circularly referenced models or break dependencies.

• Middleware Ignored

  • Symptom: Auth/middleware requirements aren’t reflected in docs.
  • Fix: Explicitly annotate with @ApiSecurity or @ApiMiddleware:

    /**
     * @ApiMiddleware("auth:api")
     */
    

Debugging

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

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

  Run with:

  php artisan dokapi:generate --debug
  

• Log Annotations Dump parsed annotations to storage/logs/dokapi_annotations.log:

  'log_annotations' => true,
  

Extension Points

• Custom Annotations Extend the annotation parser by implementing Dokapi\Rest\Contracts\AnnotationParser:

  namespace App\Extensions;
  
  use Dokapi\Rest\Contracts\AnnotationParser;
  use Dokapi\Rest\Models\Annotation;
  
  class CustomParser implements AnnotationParser
  {
      public function parse(string $annotation): ?Annotation
      {
          // Handle custom annotations (e.g., @ApiDeprecated)
          return new Annotation(...);
      }
  }
  

  Register in config/dokapi.php:

  'parsers' => [
      \Dokapi\Rest\Parsers\DefaultParser::class,
      \App\Extensions\CustomParser::class,
  ],
  

• Post-Processing Hooks Modify generated docs via Dokapi\Rest\Events\DocsGenerated:

  use Dokapi\Rest\Events\DocsGenerated;
  
  DocsGenerated::listen(function ($event) {
      $event->docs->info->title = 'My Awesome API';
  });
  

Configuration Quirks

• Base Path Handling

  • Ensure api.base_path in config/dokapi.php matches your Laravel url config:

    'api' => [
        'base_path' => env('API_BASE_PATH', '/api'),
    ],
    

  • For subdomain APIs (e.g., api.yourdomain.com), set:

    'api' => [
        'base_path' => env('API_BASE_PATH', ''),
        'host' => env('API_HOST', 'api.yourdomain.com'),
    ],
    

• Schema Resolution

  • Use $ref sparingly for large schemas to avoid bloated docs.
  • Prefer inline schemas for simple models:

    "response": {
        "200": {
            "type": "object",
            "properties": {
                "id": {"type": "integer"},
                "name": {"type": "string"}
            }
        }
    }