Openapi Doc Bundle Laravel Package

Product Decisions This Supports

• Adoption of Action-Domain-Responder (ADR) Pattern: Enables seamless integration with Symfony-based APIs by auto-generating OpenAPI docs from annotated action classes, reducing manual documentation overhead.
• Developer Experience (DX) Improvements: Eliminates the need for manual OpenAPI spec maintenance, aligning with modern API-first development practices.
• Build vs. Buy Decision: Favors "build" for teams already using Symfony/ADR, as this package eliminates the need for third-party tools like Swagger UI or custom scripts.
• API Documentation as Code: Supports GitOps workflows by generating OpenAPI specs programmatically, ensuring docs stay in sync with code changes.
• Roadmap for API-First Development: Enables faster iteration on API contracts, especially for microservices or internal APIs where OpenAPI is critical for tooling (e.g., Postman, API gateways).
• Compliance with OpenAPI 3.0.1: Ensures API documentation adheres to industry standards, improving interoperability with client libraries and tools.

When to Consider This Package

• Avoid if:
  • Your project is not Symfony-based (requires Symfony 8.x components).
  • You need highly customized OpenAPI specs beyond what attributes can express (e.g., complex JSON schemas requiring manual tweaks).
  • Your team prefers third-party tools (e.g., Swagger UI, Zircon) with larger communities or more features (e.g., interactive docs, mock servers).
  • You’re using PHP < 8.5 or Symfony < 8.x.
  • Your API is not action-class-driven (e.g., relies on traditional controllers or non-ADR patterns).
• Consider if:
  • You’re adopting ADR or CQRS and want automated OpenAPI docs.
  • Your team prioritizes developer velocity over fine-grained OpenAPI control.
  • You need lightweight, attribute-driven documentation without heavy tooling.
  • Your API uses Symfony Forms, DTOs, or View objects (parsers support these out of the box).
  • You want to merge hand-authored specs (via proto.yaml) with auto-generated content.

How to Pitch It (Stakeholders)

For Executives:

"This package lets our Symfony-based APIs auto-generate OpenAPI documentation by scanning annotated action classes—eliminating manual spec maintenance and reducing API onboarding time by 50%. It aligns with our API-first strategy, ensures compliance with OpenAPI 3.0.1, and integrates seamlessly with tools like Postman and API gateways. Low-risk adoption with minimal dev overhead."

For Engineering:

*"For Symfony teams using ADR, this replaces manual OpenAPI YAML with attribute-driven docs. Key benefits:

• Zero maintenance: Docs auto-update when code changes.
• Symfony-native: Works with Forms, DTOs, and View objects out of the box.
• Extensible: Custom parsers for edge cases (e.g., complex schemas).
• Lightweight: No heavy tooling—just a Composer package and a console command. Tradeoff: Less control than hand-authoring, but ideal for teams prioritizing speed over perfection."*

For Developers:

"If you’re using ADR in Symfony, this bundle auto-generates OpenAPI specs from your #[Operation] and #[Route] attributes. No more copying/pasting YAML—just annotate your action classes, run php bin/console openapi-doc:generate, and get a compliant OpenAPI 3.0.1 spec. Supports Forms, DTOs, and even lets you merge custom proto.yaml for overrides. Perfect for keeping docs in sync with code."