Framework Extra Bundle Laravel Package

Product Decisions This Supports

• API Documentation & Developer Experience (DX):

  • Accelerate API development by automating OpenAPI (Swagger) documentation generation, reducing manual effort and improving consistency.
  • Enable self-documenting controllers via annotations (#[OpenApi\Tag], #[OpenApi\Operation]), aligning with modern PHP attributes (Symfony 6+).
  • Replace or supplement FOSRestBundle for REST API standardization, reducing dependency bloat.

• Roadmap Priorities:

  • Phase 1: Integrate into existing Symfony projects to eliminate manual OpenAPI documentation (e.g., for public APIs, partner integrations).
  • Phase 2: Leverage response serialization (@Serialization) to standardize API responses (status codes, headers, serializer groups) across microservices.
  • Phase 3: Explore query parameter injection and dynamic versioning (via listeners) for advanced use cases (e.g., versioned APIs, multi-tenant systems).

• Build vs. Buy:

  • Buy: Avoid reinventing OpenAPI generation from scratch; this bundle provides a Symfony-native solution with minimal setup.
  • Customize: Extend the bundle’s listener system (e.g., VersionListener) to adapt to project-specific needs (e.g., API versioning, custom headers).
  • Alternatives: Compare to NelmioApiDocBundle (simpler) or API Platform (more opinionated); this bundle offers fine-grained control over serialization and annotations.

• Use Cases:

  • Public APIs: Automate Swagger UI generation for developer portals.
  • Internal Services: Standardize response formats across microservices (e.g., 201 Created with Location header).
  • Legacy Systems: Gradually add annotations to existing controllers without full refactoring.
  • Multi-Environment: Use enableDoctrineSupport and definitionAliases to manage entity references (e.g., App\Entity\User → User).

When to Consider This Package

• Adopt When:

  • Your team uses Symfony and needs OpenAPI documentation with minimal boilerplate.
  • You want annotation-driven API design (similar to SpringDoc or Swagger annotations) but with Symfony integration.
  • You’re building a REST API and want to standardize responses (status codes, headers, serialization groups) without FOSRestBundle.
  • Your project requires dynamic API versioning or custom serialization logic (e.g., per-route serializer groups).
  • You’re open to a WIP package and can contribute to its growth (low stars but high opportunity score).

• Look Elsewhere If:

  • You need production-ready stability: The package is early-stage (WIP, no dependents, no stars).
  • Your stack is non-Symfony (e.g., Laravel, Express, Django).
  • You require GraphQL support (this is REST/OpenAPI-focused).
  • You prefer zero-configuration solutions (e.g., NelmioApiDocBundle for basic docs).
  • Your team lacks Symfony expertise to configure annotations/listeners.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us automate API documentation and standardize responses across our Symfony services with minimal developer overhead. By using annotations (like #[OpenApi\Tag]), our team can document APIs as they code, reducing the time spent on manual Swagger files. It also gives us a lightweight alternative to FOSRestBundle, cutting dependency complexity. Early adoption could save 10–20 hours/month on API maintenance, and the dynamic versioning feature aligns with our roadmap for multi-environment APIs."

Risk: Low—it’s a small, focused bundle with high upside for DX. We can pilot it on one service (e.g., the User API) before scaling.

For Engineering:

*"This bundle integrates draw/* components into Symfony to handle two key pain points:

1. OpenAPI Generation: Add #[OpenApi\Operation] to controllers to auto-generate Swagger docs—no more manual YAML/JSON.
2. Response Standardization: Use @Serialization annotations to control HTTP status codes, headers, and serializer groups per endpoint.

Why it’s better than alternatives:

• More control than NelmioApiDocBundle (custom serialization, query params).
• Lighter than FOSRestBundle (no full REST layer).
• Future-proof: Supports dynamic versioning via listeners (e.g., /api/v1/...).

How to start:

1. Install the bundle and configure draw_open_api in config/packages/draw_framework_extra.yaml.
2. Add annotations to controllers (e.g., #[OpenApi\Tag("Users")]).
3. Enable responseConverter: true for auto-serialization.
4. (Optional) Extend with listeners for versioning or custom logic.

Pilot plan: Let’s try it on the Order API to replace our current manual OpenAPI docs and see how it handles serialization."*

Trade-offs:

• WIP status: We’ll need to monitor updates or contribute fixes.
• Learning curve: Annotations are new but align with Symfony’s attribute system."