Swagger Bundle Laravel Package

Product Decisions This Supports

• API Documentation as a First-Class Citizen: Accelerates adoption of OpenAPI/Swagger standards by automating documentation generation from existing code (controllers/entities), reducing manual effort and improving consistency.
• Developer Experience (DX) Investment: Enables self-service API discovery for backend engineers, reducing dependency on PMs/tech writers for up-to-date specs.
• Security-First API Design: Built-in token protection for /_swagger aligns with internal security policies (e.g., avoiding public API exposure).
• Roadmap for API-First Strategy:
  • Phase 1: Automate Swagger generation for existing APIs (reduce tech debt).
  • Phase 2: Enforce Swagger annotations in PR templates to standardize API design.
  • Phase 3: Integrate with CI/CD to validate OpenAPI compliance pre-deployment.
• Build vs. Buy: Avoids reinventing Swagger generation (leverages zircote/swagger-php) while adding Symfony-specific conveniences (e.g., bundle structure, token auth).
• Use Cases:
  • Internal developer portals (e.g., /_swagger linked in Confluence).
  • Client-facing API portals (with token restrictions).
  • Compliance/audit trails (documentation tied to code).

When to Consider This Package

• Adopt if:
  • Your team uses Symfony 6.4+ and PHP 8.1+ (hard dependency).
  • You prioritize code-first API documentation (annotations over manual .yaml files).
  • You need minimal setup for Swagger (no custom controllers/routes to configure).
  • Your API security model allows token-protected endpoints (not for public APIs).
  • You’re already using zircote/swagger-php or willing to adopt it.
• Look elsewhere if:
  • You need advanced Swagger UI customization (this bundle focuses on JSON generation).
  • Your stack is non-Symfony (e.g., Laravel, custom PHP).
  • You require real-time collaboration tools (e.g., Stoplight, SwaggerHub).
  • Your APIs are highly dynamic (e.g., GraphQL, where static annotations are limiting).
  • You need multi-format output (e.g., Postman collections, Redoc).
  • Your team lacks Symfony familiarity (bundle setup adds minor complexity).

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us automate 90% of our API documentation by generating OpenAPI specs directly from our Symfony codebase—no more outdated .yaml files or manual updates. It’s a low-risk, high-reward investment:

• Saves time: Developers document APIs as they code (via annotations).
• Reduces errors: Specs stay in sync with the codebase.
• Enables compliance: Built-in security (token protection) aligns with our API governance.
• Future-proof: Integrates with tools like Postman, Swagger UI, and CI/CD pipelines. Cost: ~$0 (open-source), with a one-time setup by the engineering team. ROI: Immediate productivity gains for API consumers (internal teams/clients)."*

For Engineering:

*"This bundle supercharges our Swagger workflow by:

1. Zero-config generation: Scans controllers/entities for annotations → swagger.json.
2. Symfony-native: Plays nice with Flex, autowiring, and security (token auth).
3. Extensible: Under the hood, it uses zircote/swagger-php, so we can customize annotations later. Tradeoffs:

• Locks us to Symfony 6.4+ (but we’re already there).
• UI is basic (just JSON; we’d still need Swagger UI or Redoc for pretty docs). Proposal: Let’s pilot this for 2–3 high-priority APIs and measure dev time saved. If it works, we can enforce annotations in our PR templates."*

For Developers:

*"This is like autopilot for Swagger:

• No more manual .yaml files: Annotate your controllers/entities, and the bundle spits out swagger.json.
• Built-in security: /_swagger requires a token (configurable in .env).
• Easy to start: Just composer require, enable the bundle, and set SWAGGER_TOKEN. Example:

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="Get users"
 * )
 */
public function getUsers(): Response { ... }

→ Boom, the spec is auto-generated. No more context-switching to update docs separately. Downside: If you hate annotations, this might feel verbose. But it’s future-proof for tools like API Platform or OpenAPI validators."*