Openapi Doc Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add to your composer.json:

   "require": {
       "chamber-orchestra/openapi-doc-bundle": "^1.0"
   }
   

   Then register in config/bundles.php:

   return [
       // ...
       ChamberOrchestra\OpenApiDocBundle\ApiDocBundle::class => ['all' => true],
   ];
   

2. First Use Case: Document an ADR Action Create an action class with #[Operation] and #[Route]:

   use ChamberOrchestra\OpenApiDocBundle\Attribute\Operation;
   use ChamberOrchestra\OpenApiDocBundle\Attribute\Route;
   use Symfony\Component\HttpFoundation\Response;
   
   #[Route('/api/users', methods: ['GET'])]
   #[Operation(description: 'List all users')]
   class ListUsersAction
   {
       public function __invoke(): Response
       {
           return new Response('[]');
       }
   }
   

3. Generate Docs Run the console command:

   php bin/console openapi-doc:generate
   

   Outputs to doc.yaml (default path).

Implementation Patterns

Core Workflow

1. Action Class Design

   • Place actions in src/Action/ (or any scanned directory).
   • Use #[Route] for HTTP metadata (path, methods).
   • Use #[Operation] for OpenAPI-specific details (description, request/response bodies).

2. DTO/Response Handling

   • For typed responses, return a DTO or class implementing Dev\ViewBundle\View\ViewInterface.
   • Example:

     #[Route('/api/users/{id}', methods: ['GET'])]
     #[Operation(responses: ['200' => new GetUserResponse()])]
     class GetUserAction { ... }
     

3. Form Integration

   • For Symfony FormTypeInterface, the FormParser auto-generates OpenAPI schemas.
   • Example:

     #[Route('/api/users', methods: ['POST'])]
     #[Operation(request: new UserType())]
     class CreateUserAction { ... }
     

4. Security Schemes

   • Define in proto.yaml:

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

   • Reference in actions:

     #[Operation(security: ['bearerAuth: []'])]
     

5. Custom Parsers

   • Extend OperationParserInterface or ComponentParserInterface for custom logic.
   • Tag in services.yaml:

     services:
         App\Parser\CustomParser:
             tags: ['openapi_doc.operation_parser']
     

Gotchas and Tips

Common Pitfalls

1. Missing Attributes

   • Error: DescriberException: Class must have both #[Operation] and #[Route].
   • Fix: Ensure all action classes include both attributes.

2. Unsupported Return Types

   • Error: Non-DTO/non-View responses may not generate schemas.
   • Fix: Use #[Operation(responses: ['200' => new \stdClass()])] for simple cases or implement a custom parser.

3. Circular References

   • Error: Infinite recursion in DTO properties.
   • Fix: Use $ref in proto.yaml or simplify DTO structure.

4. Parser Order Matters

   • Issue: Parsers run in service ID order. Override with priority tag:

     tags: ['openapi_doc.operation_parser', { priority: 100 }]
     

Debugging Tips

• Dry Run: Use --dry-run flag to inspect parsed data without writing files.
• Registry Inspection: Access registries via Symfony DI:

  $operationRegistry = $container->get(OperationRegistry::class);
  $operations = $operationRegistry->toArray();
  

• Parser Logging: Enable debug mode to see parser execution:

  php bin/console debug:config chamber_orchestra_openapi_doc
  

Extension Points

1. Custom Attributes

   • Extend #[Property] for fine-grained schema control:

     #[Property(required: true, attr: ['example' => 'value'])]
     public string $name;
     

2. Proto.yaml Merging

   • Override generated schemas in proto.yaml:

     components:
       schemas:
         User:
           type: object
           properties:
             id: { type: integer, readOnly: true }
     

3. Conditional Documentation

   • Skip actions with #[Ignore] (custom attribute) by creating a parser to filter them.

4. Performance

   • Cache registries in production:

     # config/packages/chamber_orchestra_openapi_doc.yaml
     chamber_orchestra_openapi_doc:
         cache: true