Swagger Bundle Laravel Package

Product Decisions This Supports

• API-First Development: Accelerates adoption of Swagger/OpenAPI standards for API documentation, enabling self-service developer onboarding and reducing manual documentation overhead.
• Roadmap for API Maturity: Supports a phased approach to API development—start with lightweight annotations (@Swagger) before migrating to full OpenAPI specs.
• Build vs. Buy: Avoids reinventing Swagger integration wheels; leverages existing draw/swagger library with minimal customization.
• Use Cases:
  • Rapid prototyping of REST APIs with Symfony.
  • Legacy API documentation modernization (e.g., annotating existing controllers).
  • Teams prioritizing developer experience over strict OpenAPI compliance initially.
  • Projects where FOSRestBundle is not a dependency (or can be phased out).

When to Consider This Package

• Adopt if:

  • Your team uses Symfony 4 and needs low-effort Swagger/OpenAPI docs via annotations.
  • You’re bootstrapping a new API and want to avoid heavy frameworks like FOSRestBundle.
  • Your API is simple to moderately complex (complex APIs may require manual OpenAPI spec overrides).
  • You’re okay with limited maintenance (last release in 2020; fork or extend if critical).
  • Your stack includes Doctrine ORM (optional but supported for entity documentation).

• Look elsewhere if:

  • You need active maintenance or Symfony 5/6+ compatibility (consider nelmio/api-doc-bundle or zircote/swagger-php).
  • Your API requires advanced OpenAPI features (e.g., async operations, WebSockets) not covered by annotations.
  • You’re already using FOSRestBundle (this bundle’s FOSRest support is deprecated).
  • You prefer YAML/JSON spec files over annotations (e.g., for CI/CD-driven API contracts).
  • Your team lacks PHP annotation experience (may introduce friction).

How to Pitch It (Stakeholders)

For Executives:

"This package lets our Symfony API team generate Swagger documentation with zero upfront cost—just add annotations to existing controllers. It’s like auto-documenting your API while you code, cutting manual work by 80%. Perfect for our [Product X] roadmap where we’re prioritizing API-first development. Since it’s MIT-licensed and leverages existing libraries, we avoid vendor lock-in while speeding up time-to-market for our [use case: partner integrations, mobile apps, etc.]. The trade-off? We’ll need to monitor for updates (last release was 2020), but the risk is low for our current scope."

For Engineering:

*"This bundle integrates draw/swagger into Symfony 4 to auto-generate OpenAPI docs from annotations (@Swagger). Key perks:

• Zero config for basic APIs: Annotate controllers with @Swagger\Tag, @Swagger\Parameter, etc., and it spits out Swagger UI.
• Lightweight: No FOSRestBundle dependency (unlike alternatives), and Doctrine support is optional.
• Flexible: Override auto-generated specs via YAML if needed (e.g., for edge cases). Downsides: Last updated in 2020 (but stable for simple APIs), and we’d need to fork if we hit limits. Proposal: Pilot on [Project Y] to validate effort vs. value before scaling."*

Action Item: "Let’s prototype this on [specific endpoint] and compare the output to our current docs. If it saves >50% time, we’ll adopt it for [phase 1 APIs]."