Openapi Laravel Package

Product Decisions This Supports

• Build vs. buy for API documentation tooling: psx/openapi provides typed PHP model classes for constructing an OpenAPI document programmatically, rather than hand-authoring YAML or templating JSON. It answers a narrow "build" question — do we invest in a type-safe spec builder, or lean on framework-native annotation/attribute tooling? For most Laravel teams the answer will be the latter.
• DevEx and API-as-a-product roadmap: A reliable, machine-generable spec is a prerequisite for SDK generation, contract testing, developer portals, and API catalogues. This package can support those downstream initiatives, but only as an internal enabler — it is not a customer-facing capability.
• Metadata-driven API architectures: If the product relies on dynamic route registries, plugin systems, or generated resources (e.g., an API gateway or headless CMS), a programmatic, type-safe spec builder reduces drift between runtime routes and published contracts.
• Not a differentiator and not a Laravel decision: The package ships no service provider, config, facade, or artisan integration. Adopting it means owning a thin Laravel integration layer ourselves — a real cost that should be weighed against the tiny adoption footprint (2 stars, 0 dependents, score 0.01).

When to Consider This Package

Consider it when:

• The team is already inside the apioo/psx ecosystem (e.g., Fusio) and wants spec generation to share the same object model.
• Specs must be assembled imperatively at runtime — from a database, plugin registry, or tenant configuration — where annotation scanning or static analysis cannot reach.
• A permissive license is required and Apache-2.0 satisfies legal review (it does).
• You are comfortable pinning a low-activity dependency and can vendor or wrap it.

Look elsewhere when:

• You want Laravel-native, attribute/annotation-driven generation — dedoc/scramble or zircote/swagger-php have orders of magnitude more adoption and community support.
• You are spec-first and want codegen from an OpenAPI document — use OpenAPI Generator or league/openapi-psr7-validator for validation instead.
• Bus-factor and long-term maintenance matter (they usually do). Two stars and zero dependents means no ecosystem signal, no community triage, and unclear release cadence; assume you will be the maintainer of last resort.
• You need validation, mocking, or spec diffing — this library builds documents, it does not exercise them.

Decision rule: adopt only if programmatic, type-safe document construction is a hard requirement and you accept a thin in-house wrapper; otherwise standardize on a mainstream tool.

How to Pitch It (Stakeholders)

To executives: This is not a strategic dependency. It is a small, permissively licensed utility that lets PHP code emit an OpenAPI specification in a type-safe way. The value is modest and internal — cleaner API contracts feeding SDKs, docs, and contract tests — and the risk is low but non-zero because the project has essentially no adoption or community. Recommendation: do not budget for it; evaluate mainstream alternatives first and treat this as a fallback for a specific technical constraint.

To engineering: The appeal is compile-time-ish safety for spec generation and fit with the psx/apioo ecosystem. The cost is that you own the Laravel integration, the upgrade path, and the bug fixes. Benchmark against dedoc/scramble (Laravel-native) and zircote/swagger-php before committing; only proceed if runtime, programmatic document assembly is genuinely required, and then keep it behind an internal interface so it can be swapped out without touching product code.