Weave Code
Laravel Api Docs Laravel Package
dedoc/laravel-api-docs
Generate OpenAPI documentation directly from your Laravel routes and code with a built-in UI for browsing endpoints. Keeps API docs in sync and reduces manual spec maintenance.
dedoc/laravel-api-docs generates complete API documentation for your Laravel application automatically by analyzing your routes, controllers, middleware, and Eloquent models. Instead of hand-writing docs that drift out of sync with the codebase, you point the generator at your app and it produces a structured reference of endpoints, parameters, and data fields.
- Documents every route and controller action, including middleware and HTTP methods
- Extracts request parameters and validation rules from form requests
- Reads Eloquent models, casts, and relationships to describe fields and types
- Outputs clean, readable markdown ready for any docs site or repository
Frequently asked questions about Laravel Api Docs
- How do I install and configure dedoc/laravel-api-docs in a Laravel application?
- Install it as a dev dependency with composer require dedoc/laravel-api-docs, which Laravel's package auto-discovery picks up without manual provider registration. Publish the config file with php artisan vendor:publish so you can control route path, middleware, and output options. Then register the documentation route behind an environment gate so the UI and JSON spec are only reachable where you want them. Most teams are up and running in a single sitting because there are no annotations to write.
- Do I need to write PHPDoc annotations or PHP attributes to generate the API documentation?
- No. The package infers the OpenAPI document from your existing route definitions, controller method signatures, FormRequest validation rules, API resources, and Eloquent models, so a conventional Laravel API gets coverage with zero annotation overhead. You only add manual overrides where inference is ambiguous or incomplete, such as custom response shapes or exotic types. This keeps the spec close to the code and removes the usual drift that comes from hand-maintained docblocks.
- Which PHP and Laravel versions does this package support?
- The package targets modern Laravel and requires PHP 8.x, but the exact floors move between releases, so check the require constraints in its composer.json before adopting it. Confirm those constraints against your runtime and your CI matrix rather than assuming compatibility from the docs alone. If you are on an older Laravel major, pin the last package version that declares support for it. Because the project is pre-1.0, the supported range can change in a minor release.
- How does it infer request bodies and response schemas from my code?
- It introspects Laravel's route collection, resolves each route to its controller action, and reads the validation rules from any FormRequest or inline validator to build the request schema, including required fields, nullability, and basic types. Response schemas come from return type hints, API resource classes, and Eloquent model attributes where it can resolve them. Inference is heuristic, so ambiguous type hints, dynamic arrays, or union types will sometimes produce imprecise schemas that need a targeted override. Treat the generated document as a reviewable draft rather than an unquestioned source of truth.
- Which OpenAPI version does the package generate, and can I opt into OpenAPI 3.2?
- OpenAPI 3.1 remains the default output, emitting a 3.1.x document, and OpenAPI 3.2 support is opt-in as of v0.13.48. Choose the emitted version explicitly in configuration instead of inheriting the default, then validate that choice against every downstream consumer such as SDK generators, gateways, and API portals. Because 3.2 is new, tooling support is uneven, so 3.1 is the safer initial posture unless you have verified 3.2 end to end. This also keeps your upgrade path contained if you need to roll back.
- How do I keep the generated API docs route out of production?
- Register the documentation route behind an environment check or a dedicated ability/middleware so it only resolves in local and staging environments, and disable it in production config. The spec exposes your full API surface, including internal endpoints, so leaving it publicly reachable is an information disclosure risk. If you must serve docs in production, put them behind authentication and consider restricting by IP or a signed URL. Verify the behavior in a real production-like environment rather than trusting the default.
- Does the generated documentation support Sanctum or Passport authentication?
- Yes. The package declares security schemes so endpoints show an authorization control in the interactive UI and the spec carries the security requirement for consumers. You configure which scheme applies, whether bearer token, Sanctum, or Passport, and can scope it per route group. It does not change how authentication actually runs at request time, so it coexists cleanly with your existing middleware stack. Confirm the emitted security block is what your consumers expect before you publish the spec.
- Can I override the generated schema for endpoints the package describes incorrectly?
- Yes, you can supply manual type mappings, custom extensions, and per-endpoint overrides through configuration rather than annotating everything. Use these surgically: fix the handful of ambiguous endpoints and leave the inferred majority alone, otherwise you rebuild the annotation burden you were avoiding. If you extend or override toArray on Generator-namespace OpenAPI objects, review the toArray to serializeAs31 serialization change in v0.13.48, since that is the one documented breaking surface in that release. Teams using the package as shipped are unaffected.
- How do I export the spec to JSON or YAML and detect spec drift in CI?
- Generate the document from a console command in your pipeline, write it to a committed JSON or YAML snapshot, and diff it on every pull request so schema changes are reviewed like code changes. That diff is your safety net against silent misinference when someone changes a validation rule or return type. Also validate the output against downstream tooling, such as an OpenAPI linter or an SDK generator, as a second gate. Run the check in non-production only, since this is a dev and CI dependency, not a runtime one.
- Is this package production ready, and how does it compare with Scribe or l5-swagger?
- It is actively maintained with a steady release cadence, but it is still pre-1.0, so pin an exact version and read changelogs instead of floating the constraint. Compared with Scribe and l5-swagger, the trade-off is zero-annotation inference and tighter Laravel idiom coverage versus the explicit control that annotation-driven tools give you. If you already maintain a hand-written spec, run this in parallel first and diff the generated document against the incumbent before retiring the old source of truth. Adopt it as a non-production dependency with a documented rollback via version pin.
Weaver
How can I help you explore Laravel packages today?