Larecipe Swagger Laravel Package

Getting Started

This package is an add-on to LaRecipe (binarytorch/larecipe). It renders an interactive Swagger UI panel inside a LaRecipe documentation page so readers can execute "Try it out" requests against your API without leaving /docs. It does nothing on its own — install LaRecipe first.

Minimal path:

1. Confirm you are already on LaRecipe (v1.x era). If not, this package is not a reason to adopt LaRecipe; use Scramble, Scribe, or a standalone Swagger UI page instead.
2. composer require binarytorch/larecipe-swagger
3. Publish the package's config/assets (check the README for the exact provider and tag — the standard Laravel pattern applies): php artisan vendor:publish --provider="BinaryTorch\LaRecipeSwagger\LaRecipeSwaggerServiceProvider"
4. Expose an OpenAPI/Swagger spec somewhere the browser can fetch it (e.g. public/docs/openapi.json, or a route returning the JSON).
5. In a LaRecipe markdown page under resources/docs/, add a fenced swagger code block containing the spec path/URL (the README shows the exact block shape — copy it verbatim, including blank lines).
6. Visit the page in your docs and confirm the UI loads and a GET can be executed.

Look first at: the package README, its published config (spec URL / base path options), the published views/blade partial it injects, and the bundled swagger-ui asset version (this tells you whether OpenAPI 3.0 is supported or only Swagger 2.0).

First real use case: a "Reference" or "Playground" docs page where each endpoint has a prose explanation in Markdown followed by a swagger block scoped to that endpoint's spec.

Implementation Patterns

• Prose + live panel per page. Keep Markdown for narrative, auth notes, and copy-paste curl examples; use the swagger block only for the interactive part. Readers with JS disabled or a blocked network still get the docs.
• Serve the spec from a route, not a stale file. Point the block at something like /api/docs/openapi.json produced by your serializer or a committed export step. A checked-in openapi.json drifts within weeks; a route keeps it honest, at the cost of the docs page depending on app health.
• Split specs per domain. One spec per docs section (billing, users, webhooks) keeps the embedded UI navigable and limits how much of the API an unauthenticated visitor can enumerate.
• Same-origin hosting. Serve the docs and the API from the same host so "Try it out" requests are same-origin. If you must cross hosts, enable CORS for the docs origin, allow the Authorization header, and avoid wildcard origins with credentials.
• Environment targeting. Configure the spec's host/basePath (Swagger 2.0) or servers (OAS3) to a local or staging URL. This is the single most useful knob: it lets the docs stay useful in dev without letting anyone fire writes at production.
• Token workflow. Bearer tokens are typically entered per operation in the UI, not persisted. Document this in the surrounding Markdown ("paste a token from php artisan tinker into the Authorize box") rather than expecting it to carry over.
• Spec validation in CI. Run swagger-cli validate or Spectral against the spec. The UI degrades quietly on malformed specs — a green CI check is cheaper than debugging a blank panel.
• Pair with tests. Use the same spec to drive contract tests; then the docs panel and your assertions cannot disagree.

Gotchas and Tips

• Archived since 2019-07-24, 35 stars, zero dependents. Assume no fixes. Pin exact versions of this package, LaRecipe, and PHP/Laravel. Anything from Laravel 8+ / PHP 8 is untested territory; vendor or fork the package if you adopt it.
• Version lock to LaRecipe. The package hooks LaRecipe's rendering pipeline and published views. A LaRecipe minor upgrade can silently break the fenced block. Upgrade both together and re-test the docs page.
• 404 on the spec is the #1 failure. The JSON/YAML must be reachable by the browser, not just by PHP. Check the Network tab before touching anything else.
• Fenced-block syntax is brittle. A missing blank line, wrong key, or an indented fence inside a list will render as a plain code block. Diff your block against the README character-for-character when the panel vanishes.
• Caches hide config changes. Run php artisan config:clear and LaRecipe's docs cache clear (often php artisan larecipe:clear) after editing config, assets, or specs.
• CSRF and session middleware. "Try it out" issues XHR from the browser. Non-GET calls routed through the web middleware stack will fail with 419. Target api routes with token auth, or whitelist the docs origin explicitly.
• Real requests, real damage. The UI will execute DELETE. Guard the docs behind LaRecipe's auth/gate plus an IP allowlist, and never ship it enabled in production.
• Swagger 2.0 vs OpenAPI 3.0. The 2019 vintage of the bundled swagger-ui determines this. If OAS3 renders blank, either downgrade the spec or replace the bundled swagger-ui dist — that's the main extension point.
• basePath/servers mismatch produces 404s that look like auth failures. Confirm the final request URL in the Network tab matches your route.
• Extension points: published config for spec location/base URL, published Blade view to restyle or wrap the panel, and the static assets directory to swap in a newer swagger-ui build. Beyond that, fork — the upstream is dormant.
• Reasonable migration: if you're starting fresh, skip this and put a Scramble/Scribe-generated spec into a single static page with official swagger-ui; you get current OAS3 support and a maintained dependency for less effort than resurrecting this one.