Api Doc Property Bundle Laravel Package

Product Decisions This Supports

• API Documentation Accuracy: Enhances NelmioApiDocBundle to expose custom properties (e.g., computed fields, metadata) not parsed by default (JSON, JMS, or Validator). Critical for APIs where documentation must reflect runtime behavior (e.g., created_at timestamps, derived fields like user.full_name).
• Developer Experience: Reduces manual documentation updates by auto-generating API specs from annotations, aligning with shift-left testing and self-documenting code principles.
• Roadmap Prioritization:
  • Build vs. Buy: Justifies not building a custom solution for property documentation if the team already uses NelmioApiDocBundle.
  • Phase 2 Adoption: Post-launch, enables adding non-standard fields (e.g., status: enum["active", "pending"]) without API contract changes.
• Use Cases:
  • Legacy Systems: Documenting APIs with complex business logic (e.g., order.total_with_tax).
  • GraphQL-like Features: Simulating nested objects in REST APIs (e.g., user.address.city).
  • Compliance: Auto-generating OpenAPI specs for regulatory documentation (e.g., GDPR data fields).

When to Consider This Package

• Adopt If:
  • Your API uses NelmioApiDocBundle and lacks support for custom properties (e.g., computed fields, metadata).
  • You need zero-code changes to expose properties—annotations suffice.
  • Your team prioritizes developer velocity over strict type safety (e.g., type="string" is flexible but not validated).
  • You’re documenting internal APIs or prototype endpoints where strict validation isn’t critical.
• Look Elsewhere If:
  • You require runtime validation of documented properties (use Symfony Validator or OpenAPI Generator).
  • Your API is highly dynamic (e.g., GraphQL)—consider GraphQL Schema Stitching or JSON Schema.
  • You need Swagger UI integration beyond basic docs (this package focuses on NelmioApiDoc, not Swagger).
  • Your team lacks PHP/Laravel expertise—low stars/maturity may deter adoption.

How to Pitch It (Stakeholders)

For Executives:

"This package lets our API documentation automatically reflect custom fields (e.g., user.full_name) without manual updates. It’s a lightweight way to improve developer onboarding and compliance—like adding seatbelts to our API specs. Low risk (MIT license, minimal setup), high reward for teams maintaining complex APIs."

For Engineering:

"If we’re already using NelmioApiDocBundle, this adds zero-boilerplate support for documenting non-standard properties (e.g., status: enum["draft", "published"]). Tradeoff: Flexible but not validated—ideal for internal APIs or prototypes. Setup takes <10 mins (Composer + annotation).

• Pros: Aligns docs with code, reduces tech debt.
• Cons: Not a replacement for runtime validation; limited to Nelmio’s ecosystem. Recommended for Phase 2 if we’re expanding API surface area."