Swagger Php Laravel Package

Product Decisions This Supports

• API Documentation as a First-Class Citizen:

  • Adopt a build-once, document-forever approach by embedding OpenAPI/Swagger annotations directly in PHP code, ensuring docs stay in sync with implementation.
  • Reduce technical debt by eliminating manual documentation updates (e.g., Swagger UI edits, Postman collections).

• Developer Experience (DX) Improvements:

  • Self-documenting code: Enforce API contracts via PHP attributes (e.g., @OAT\Get, @OAT\Response), catching issues early via IDE tooling (e.g., PHPStorm’s attribute validation).
  • Onboarding acceleration: New engineers can explore endpoints via interactive Swagger UI without reading code.

• Roadmap Priorities:

  • API-First Development: Mandate OpenAPI annotations for all new endpoints (aligns with OpenAPI 3.1/3.2 features like unevaluatedProperties).
  • Tooling Integration: Integrate with CI/CD to auto-generate and validate OpenAPI specs on PRs (e.g., fail builds if spec is invalid).
  • Multi-Version Support: Standardize on OpenAPI 3.2 for future-proofing (e.g., JSON Schema 2020-12 support).

• Build vs. Buy:

  • Buy: Avoid reinventing wheel (e.g., custom PHPDoc parsers, CLI tools). This package handles edge cases (e.g., generic types, nested schemas) out-of-the-box.
  • Customization: Extend via Generator hooks (e.g., add custom filters for internal endpoints).

• Use Cases:

  • Public APIs: Generate Swagger UI for developer portals (e.g., /api/docs).
  • Internal APIs: Secure docs behind auth (e.g., via securitySchemes in OpenAPI).
  • Microservices: Centralize API contracts across services (e.g., shared OpenAPI specs via Git submodules).

When to Consider This Package

Adopt When:

• Your team uses PHP 8.2+ and Laravel/Symfony (or similar frameworks with attribute support).
• You need interactive API docs (Swagger UI, Redoc) with zero manual maintenance.
• Your API has complex schemas (e.g., generics, unions, nested objects) requiring automatic type resolution.
• You’re migrating from PHPDoc annotations to modern PHP attributes (deprecated support remains for legacy code).
• You want OpenAPI 3.2 compliance (e.g., for JSON Schema 2020-12 or unevaluatedProperties).

Look Elsewhere If:

• You’re not using PHP (consider swagger-codegen for other languages).
• Your API is extremely simple (e.g., CRUD endpoints with no custom validation).
• You need real-time API docs (this generates static specs; pair with tools like Stoplight for live updates).
• Your team resists code-based documentation (political risk > technical benefit).
• You require custom OpenAPI extensions beyond standard attributes (may need post-processing).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us automate 90% of API documentation by embedding specs directly in our PHP code. Instead of maintaining separate Swagger files that drift from reality, every endpoint’s contract is defined once—via PHP attributes—and stays in sync forever. This reduces onboarding time for new engineers, cuts documentation errors, and future-proofs our APIs for OpenAPI 3.2. For example, our /users endpoint’s Swagger UI will always reflect its actual parameters, responses, and auth requirements—no manual updates needed. The cost? A one-time migration to attributes (with backward-compatible PHPDoc support) and a CLI tool to generate docs on demand. ROI: fewer bugs, faster dev cycles, and happier API consumers."

For Engineers:

*"swagger-php lets us write self-documenting APIs using PHP 8.2 attributes (e.g., @OAT\Post, @OAT\Response). Key wins:

• No more doc-schema drift: Docs are generated from code, so they’re always accurate.
• IDE-friendly: Attributes trigger autocompletion and validation (e.g., catch missing description in @OAT\Get).
• Flexible output: Generate OpenAPI 3.0/3.1/3.2 specs as YAML/JSON, or use the CLI to auto-update /api/docs.
• Modern PHP support: Handles generics (array<User|Admin>), unions, and complex types via symfony/type-info.
• CI/CD ready: Add a script to validate specs on PRs (e.g., fail if a new endpoint lacks a @OAT\Info title).

Migration path: Start with a single controller, then expand. Legacy PHPDoc annotations still work (but are deprecated). Example:

#[OAT\Get(path: '/users/{id}', responses: [new OAT\Response(ref: '#/components/schemas/User')])]
public function show(User $user) { ... }
```"*

For QA/DevOps:

*"This ensures API contracts are version-controlled alongside code. Key benefits:

• Automated spec generation: Run ./vendor/bin/openapi to update /api/docs in CI.
• Early error detection: Invalid OpenAPI (e.g., missing summary in @OAT\Post) fails fast.
• Tooling integration: Works with Swagger UI, Postman, and API gateways (e.g., Kong) out-of-the-box.
• Audit trail: All endpoints are documented by definition—no hidden or undocumented routes.

Action item: Add a pre-commit hook or GitHub Action to lint OpenAPI specs before merge."*