Apidoc Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ehyiah/apidoc-bundle
   

   Ensure composer config extra.symfony.allow-contrib true is set.

2. First Use Case: Create a basic YAML file at config/api_doc/swagger.yaml:

   openapi: 3.0.0
   info:
     title: My API
     version: 1.0.0
   paths:
     /api/users:
       get:
         summary: Get all users
         responses:
           200:
             description: OK
   

3. Enable UI: Configure config/packages/ehyiah_api_doc.yaml:

   ehyiah_api_doc:
       ui: swagger
   

4. Access Docs: Visit /api/doc in your browser to see the Swagger UI.

Implementation Patterns

Usage Patterns

1. YAML-First Workflow:

   • Store API specs in config/api_doc/ (e.g., users.yaml, auth.yaml).
   • Use php bin/console apidoc:generate to validate and merge files into a single OpenAPI spec.
   • Reference partials with !include in YAML:

     paths:
       !include users.yaml
     

2. PHP-Class Integration:

   • Annotate controllers with @ApiDoc attributes:

     use Ehyiah\ApiDocBundle\Annotation\ApiDoc;
     
     #[ApiDoc(
       path: "/api/users",
       methods: ["GET"],
       summary: "Get all users"
     )]
     class UserController extends AbstractController { ... }
     

   • Generate PHP classes from YAML:

     php bin/console apidoc:generate:classes
     

3. Hybrid Approach:

   • Use YAML for static specs (e.g., global schemas, security definitions).
   • Use PHP classes for dynamic routes (e.g., controller-specific endpoints).
   • Merge them in config/packages/ehyiah_api_doc.yaml:

     ehyiah_api_doc:
       sources:
         - { type: yaml, path: "%kernel.project_dir%/config/api_doc" }
         - { type: php, path: "%kernel.project_dir%/src/ApiDoc" }
     

4. UI Routing:

   • Route the UI to a custom path (e.g., /docs) by overriding the controller:

     ehyiah_api_doc:
       ui: swagger
       route:
         path: /docs
         controller: App\Controller\CustomApiDocController
     

Workflows

• Development:

  • Edit YAML/PHP files, then run apidoc:generate to validate.
  • Use apidoc:serve to spin up a local Swagger UI server for testing:

    php bin/console apidoc:serve
    

• CI/CD:

  • Add apidoc:generate to your test suite to catch spec errors early.
  • Generate HTML reports with apidoc:generate:report for documentation sites.

• IDE Integration:

  • Use @ApiDoc attributes to link controllers to their docs in PhpStorm/VSCode via PHP Annotations.

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Clear the cache after changing YAML/PHP files:

     php bin/console cache:clear
     

   • Disable caching during development in config/packages/ehyiah_api_doc.yaml:

     ehyiah_api_doc:
       cache: false
     

2. YAML Parsing Errors:

   • Validate YAML files with apidoc:validate before merging:

     php bin/console apidoc:validate config/api_doc/swagger.yaml
     

   • Common issues:
     • Indentation (use spaces, not tabs).
     • Unquoted keys (e.g., 200: must be "200": in strict YAML).

3. PHP Class Conflicts:

   • Ensure PHP classes extend Ehyiah\ApiDocBundle\Model\AbstractApiDoc or implement Ehyiah\ApiDocBundle\Model\ApiDocInterface.
   • Avoid naming conflicts with YAML files (e.g., User.yaml vs. User.php).

4. UI Rendering:

   • Some UIs (e.g., Redoc) may fail with malformed specs. Test with Swagger UI first:

     ehyiah_api_doc:
       ui: swagger  # Default; switch to 'redoc' later
     

Debugging

• Log Generation: Enable debug logs in config/packages/monolog.yaml:

  handlers:
      api_doc:
          type: stream
          path: "%kernel.logs_dir%/apidoc.log"
          level: debug
  

  Then check logs for parsing errors during apidoc:generate.

• Dry Runs: Use --dry-run to preview changes without writing files:

  php bin/console apidoc:generate --dry-run
  

Tips

1. Schema Reuse:

   • Define reusable schemas in YAML (e.g., schemas/user.yaml) and reference them:

     components:
       schemas:
         User: !include schemas/user.yaml
     

2. Security Definitions:

   • Centralize OAuth2/JWT configs in YAML:

     components:
       securitySchemes:
         bearerAuth:
           type: http
           scheme: bearer
           bearerFormat: JWT
     

   • Apply globally in paths:

     paths:
       /api/secure:
         security:
           - bearerAuth: []
     

3. Dynamic Paths:

   • Use PHP classes for routes with dynamic parameters:

     #[ApiDoc(
       path: "/api/users/{id}",
       methods: ["GET"],
       summary: "Get a user by ID",
       parameters: [
         new Parameter(name: "id", in: "path", required: true, schema: new \OpenApi\Schemas\Schema(type: "integer"))
       ]
     )]
     

4. Extensions:

   • Override the generator to add custom logic (e.g., auto-generate examples):

     // src/ApiDoc/Generator/CustomGenerator.php
     namespace App\ApiDoc\Generator;
     use Ehyiah\ApiDocBundle\Generator\AbstractGenerator;
     
     class CustomGenerator extends AbstractGenerator {
         public function generate(): void {
             parent::generate();
             // Add custom logic here
         }
     }
     

     Then configure in config/packages/ehyiah_api_doc.yaml:

     ehyiah_api_doc:
       generator: App\ApiDoc\Generator\CustomGenerator
     

5. Versioning:

   • Use tags to version your API:

     paths:
       /api/v1/users:
         tags: [v1]
     

   • Filter by tag in Swagger UI’s "Explore" dropdown.