Schema Generator Laravel Package

Product Decisions This Supports

• API Documentation Automation: Accelerates generation of OpenAPI-compliant JSON schemas for PHP classes (DTOs, entities, enums, value objects), reducing manual documentation effort by 70%+.
• Consistent API Contracts: Enables standardized schema definitions across microservices, improving interoperability and reducing integration errors.
• Developer Productivity: Eliminates repetitive schema writing for CRUD endpoints, allowing engineers to focus on business logic (e.g., reducing schema generation time from 2 hours to 10 minutes per endpoint).
• Roadmap for API-First Development: Justifies investment in API-first architecture by providing tooling to maintain schemas in sync with code (e.g., "Schema-as-code" principle).
• Build vs. Buy: Favors build over commercial tools (e.g., Swagger Codegen) for teams already using Laravel/PHP, with lower total cost of ownership (MIT license, no vendor lock-in).
• Use Cases:
  • Internal developer portals (e.g., integrating with API documentation tools like Redoc or Swagger UI).
  • GraphQL schema stitching (generating input/output types for GraphQL APIs).
  • Legacy system modernization (auto-generating schemas for existing PHP classes).

When to Consider This Package

• Adopt if:
  • Your team uses PHP/Laravel and maintains OpenAPI/Swagger documentation.
  • You have hundreds of DTOs/entities and need to reduce schema maintenance overhead.
  • Your API contracts are tightly coupled to PHP classes (e.g., DDD value objects, entities).
  • You prioritize developer experience over full OpenAPI feature parity (e.g., paths/operations are handled elsewhere).
• Look elsewhere if:
  • You need full OpenAPI spec generation (paths, endpoints, security schemes) → Use zircote/swagger-php or darkaonline/l5-swagger.
  • Your stack is non-PHP (Node.js/Python/Java) → Use language-specific tools (e.g., OpenAPI Generator).
  • You require real-time schema validation → Combine with respect/validation or [symfony/validator].
  • Your team lacks PHP type hints → Schema generation will be less accurate.
  • You need custom schema transformations beyond what the package supports (e.g., complex JSONLogic rules).

How to Pitch It (Stakeholders)

For Executives (1-minute pitch)

"This package automates 90% of our API documentation work by generating OpenAPI schemas directly from our PHP classes—DTOs, entities, and enums. For example, instead of manually writing YAML for a UserProfile DTO, we’ll auto-generate it from the class definition. This cuts documentation time by 80%, reduces errors from drift between code and docs, and aligns with our API-first roadmap. It’s a low-risk, high-reward tool (MIT license, PHP-native) that pays for itself in developer hours. We’ll pilot it on our /users API to prove ROI before scaling."

Key Outcomes: ✅ Faster releases (no manual schema updates). ✅ Consistent contracts (schemas stay in sync with code). ✅ Lower tooling costs (no SaaS subscriptions).

For Engineering (Technical Deep Dive)

*"This is a schema generator for PHP classes that outputs OpenAPI-compliant JSON schemas via cebe/php-openapi. It’s ideal for Laravel apps with typed DTOs/entities because it:

1. Auto-generates schemas for:
   • DTOs (required/optional fields, defaults).
   • Enums (string/int values).
   • Value objects (regex patterns, string formats).
   • Entities (constructor args + set* methods).
2. Handles references (e.g., $ref: '#/components/schemas/Gender-post') for reusable components.
3. Supports customization via #[SchemaMethod] for edge cases.

Why not alternatives?

• zircote/swagger-php: Full OpenAPI but heavier; this is lighter for schema-only needs.
• Manual YAML: Error-prone and unscalable.

Implementation Plan:

1. Pilot: Generate schemas for 3 critical DTOs (e.g., Order, User, Payment).
2. Integrate: Plug into our CI to auto-update docs on git push.
3. Extend: Add #[SchemaMethod] for custom schemas (e.g., password fields).

Trade-offs:

• ⚠️ Limitation: Doesn’t generate paths/endpoints (use alongside darkaonline/l5-swagger).
• ⚠️ Maturity: Low stars but MIT-licensed and actively maintained in a monorepo.

Next Steps:

• Review the example usage.
• Prototype with our UserDto class to validate output.
• Align with the API team on OpenAPI tooling (e.g., Redoc integration)."*