stixx/openapi-command-bundle
A Symfony bundle that adds console commands for working with OpenAPI specs, making it easier to generate, validate, and manage API documentation from the CLI during development and CI workflows.
This package wraps OpenAPI document generation behind artisan/console commands so specs can be produced from code rather than hand-maintained YAML. Start by reading the package's README for the command namespace and the config file it publishes — that config is where document paths, scan directories, and generation options live.
Minimal path to first value:
php artisan vendor:publish or the package's equivalent), then set your source scan paths and output file locations.The most common first use case is replacing a hand-written openapi.yaml with a generated one committed to the repo, so diffs are reviewable in pull requests.
Generate in CI, commit the artifact. Run the generation command in a CI job and fail the build if git diff on the spec is non-empty. This gives you contract review on every PR without requiring every developer to remember to regenerate.
Generate at deploy time instead. If you don't want specs in the repo, run the command during your release step (after composer install, before the container is sealed). This is the pattern where build-time warming matters — see the gotchas section.
Separate public and internal specs. Define two documents in config (e.g. public and internal) with different scan paths or filters. Internal-only endpoints then never leak into the customer-facing spec.
Contract testing loop. Feed the generated spec into Dredd/Schemathesis/OpenAPI validation in a test job. Because the spec is generated from the same source as the routes, drift is caught cheaply.
Docs route for non-production. Expose the generated document via a route gated on app()->environment('local') or a feature flag, so developers can browse live docs without publishing anything.
Laravel integration tip. If the package ships Symfony-style DI wiring, register the commands from your AppServiceProvider or a dedicated provider and confirm php artisan list shows them. Command classes are usually resolvable straight from the container, so you can also call the underlying generator service in a queued job if you need to regenerate on content changes.
0.15.0 is the important one: build-time warming is now opt-in. If you relied on 0.14.x regenerating documents automatically during a build/cache-warm step, that no longer happens silently. Symptoms after upgrading: a stale spec file, a docs UI serving an old schema, or contract tests passing against last week's API. Fix by explicitly enabling warming in the config (or the command flag the PR introduces), or by adding the generate command directly to your pipeline. This is the kind of change that fails quietly in production rather than loudly in CI — audit any deploy script that assumed warming.
Stale artifacts are the default failure mode generally. Whatever you choose — commit the spec or generate on deploy — make it deterministic and asserted somewhere. A git diff --exit-code check or a "spec is newer than sources" check saves a lot of confusion.
Watch the Symfony-vs-Laravel seam. The package's naming and lifecycle assume a console/kernel warmup model. In Laravel the warmup hooks are different, so anything documented as "runs at build time" deserves a manual verification in your own pipeline rather than trust in the docs.
Version is pre-1.0. At 0.15.x, minor bumps can carry behavior changes (this release proves it). Pin the version and read the changelog on every bump; don't use a ^0.15 range if the spec is a released artifact.
Debugging generation output. When a path is missing from the spec, check scan paths first, then route registration order, then any document-level filters. Most "missing endpoint" reports are a path/namespace mismatch, not a parsing failure.
Extension point. Keep your own thin wrapper command around the package's generator so you can add post-processing (sorting keys for stable diffs, injecting servers/security schemes per environment) without forking. Stable key ordering in particular makes committed specs diff-friendly.
How can I help you explore Laravel packages today?