Openapi Toolbox Laravel Package

Getting Started

1. Install the package and let Laravel auto-discover the service provider:

   composer require blumilksoftware/openapi-toolbox
   

2. Publish the package config. Run php artisan vendor:publish and select the OpenAPI Toolbox entry, then open the generated config file (typically config/openapi-toolbox.php or similar — confirm the path in the service provider's publishes() method).
3. In v3 the config is oriented around named documentations. Start with a single entry before adding more:

   'documentations' => [
       'default' => [
           'routes' => [
               // route names, prefixes, or middleware groups to include
           ],
           'output' => storage_path('openapi/default.json'),
       ],
   ],
   

4. Generate the spec with the package's Artisan command. Run php artisan list openapi to see the exact command and options in your installed version, then generate:

   php artisan openapi:generate
   

5. Open the generated JSON/YAML in your editor or point Swagger UI / Redoc at it. For a first use case, document one controller or route group, generate the file, and commit it so reviewers can see the API contract change alongside the code.

Where to look first:

• The published config file — it is the main extension point in v3.
• The package's Artisan commands (php artisan list openapi).
• The docs/ or README section on documentations and caching, since those are the major v3 additions.

Implementation Patterns

One documentation per audience. Define separate entries for public, admin, or partner APIs rather than trying to filter one giant spec at consumption time. Generate each independently:

php artisan openapi:generate --documentation=public
php artisan openapi:generate --documentation=admin

Keep output paths distinct and serve each spec from its own docs route or static file.

Generate in CI and diff the artifact. Add a pipeline step that runs generation and fails if the committed spec changes unexpectedly. This turns undocumented endpoint changes into review comments instead of production surprises. Pair it with a validator such as Spectral for linting the generated OpenAPI.

Configure caching deliberately. v3 makes the cache configurable. Set an explicit cache store and TTL per environment rather than relying on defaults. In local development, prefer disabling the cache or using a short TTL so route/attribute changes are reflected immediately. In production, warm the cache during deployment.

Serve docs behind access control. Expose generated documentation through a route or static file, but gate it with middleware in non-local environments. Documentation often reveals internal routes and payload shapes.

Reuse schemas through attributes/components. Define request and response schemas once (attributes, form requests, or shared component definitions) and reference them across endpoints. This keeps generated specs consistent and makes breaking changes visible in one place.

Keep generation close to route definitions. When a route changes, the corresponding attribute or config entry should change in the same PR. Treat the generated file as a build artifact that is either committed intentionally or produced only in CI — pick one policy and enforce it.

Gotchas and Tips

• v3 config restructuring. The jump from v2 to v3 introduces multiple documentations and changes the config shape. Do not merge the old config blindly — republish it, then migrate your single-documentation settings into a named entry. If your app read config keys directly, audit those references.
• Breaking change risk from abandoned custom dependencies. The release drops custom dependencies from the core. If you extended package internals or relied on transitive packages that were previously pulled in, add those dependencies explicitly to your own composer.json and re-test generation.
• Stale cache after route changes. A cached spec will not reflect new routes, attributes, or config changes. Clear the relevant cache key/store as part of deployment, and make sure each named documentation has an independent cache key so regenerating one does not invalidate another unexpectedly.
• Cache driver differences. Array/file/Redis stores behave differently across environments. Verify generation works with the cache disabled before debugging why a change "isn't showing up."
• Closure routes and dynamic route registration are harder to introspect. Prefer controller-based routes with explicit attributes when you need reliable output.
• Route caching interactions. If you run php artisan route:cache, regenerate documentation after clearing and rebuilding the route cache; stale route caches can produce incomplete specs.
• Large specs can be slow. Generation time grows with the number of routes and schemas. If CI slows down, generate only the documentation affected by the changed paths, or cache aggressively and regenerate on a schedule.
• Validate before publishing. Treat malformed output as a build failure. A JSON schema validation step catches missing $refs and invalid component names before consumers do.
• Extension points: prefer the published config, custom attributes, and Artisan command options over subclassing package internals. Internal classes are the most likely thing to move in a major release like this one.