Df Apidoc Laravel Package

Getting Started

dreamfactory/df-apidoc is not a package you composer require into a normal Laravel app. It is a module of the DreamFactory platform — it ships as a dependency of dreamfactory/dreamfactory, and expects the platform's service-provider bootstrapping, module loader, RBAC layer, and route registration. Treat it as internal platform code you happen to be able to read.

Concretely:

• If you run DreamFactory (Docker image or a composer install of the platform), it is already installed. Confirm with composer show dreamfactory/df-apidoc and php artisan route:list | grep api_doc.
• If you have a vanilla Laravel app: stop here. You would burn more time stubbing DreamFactory's Service contracts than writing docs by hand. Use darkaonline/l5-swagger or dedoc/scramble instead.
• Where to look first: the controller that assembles the spec (it walks each service and serializes its routes/params), the package's merged config, and the platform's API Docs tab in the admin UI — that UI is the fastest way to see what the package actually emits before you write any integration code.
• First use case: authenticate to your instance and pull the platform spec from the api_docs endpoints (/api/v2/api_docs for the platform, /api/v2/api_docs/{service} for a single service). Point Swagger UI, Redoc, or a Postman import at those URLs and you immediately have live documentation for every service you have configured — with zero annotations to maintain.

Implementation Patterns

Spec-as-artifact. Don't consume the endpoint ad hoc. Fetch it during build/deploy, write openapi.json into your repo or release artifact, and diff it in CI. API surface changes then show up as reviewable PRs instead of surprising your consumers in production.

Per-service generation. The platform-wide spec is large and mostly irrelevant to any one consumer. Generate clients with openapi-generator against /api/v2/api_docs/{service} for the service you actually care about, so you get a small typed SDK rather than a 40-endpoint monolith.

Contract smoke tests. Parse paths out of the spec and assert each one exists in staging using Laravel's Http:: client. This catches the classic failure where a service is deployed but not registered (or registered under a different alias) long before a user finds it.

Custom services plug in for free. If your service extends DreamFactory's Service base and declares its routes the normal way, its documentation appears automatically. Put human-readable descriptions in the service's doc metadata / docblocks rather than hand-editing generated JSON — anything hand-edited is lost on the next regeneration.

Public developer portals. If you need to expose docs outside the admin boundary, proxy the DreamFactory endpoint through your own tiny controller: fetch with a role-scoped key, strip internal-only paths, cache the result for a few minutes, serve it. Don't expose the platform endpoint with an admin token — see below.

Gotchas and Tips

• The spec is permission-scoped. The document returned reflects the calling role's access. A spec pulled with an admin API key lists endpoints your actual consumers cannot call, and they will file bugs about 401s. Always generate with the same role the consumers use.
• Caching is the #1 "the package is broken" cause. DreamFactory caches platform and service metadata aggressively. If a new endpoint or param does not appear, run php artisan cache:clear and config:clear, and check the platform's cache config, before assuming a bug.
• OpenAPI 2.0 vs 3.0. Historically Swagger 2.0 output; newer builds add OpenAPI 3. openapi-generator produces materially different clients between the two. Pick a format explicitly in your fetch script and pin it, rather than relying on the default.
• Wrong hosts behind a proxy. host/basePath/servers are derived from the incoming request. Behind nginx, Traefik, or a load balancer you will get internal hostnames in the spec. Fix trusted-proxy config and APP_URL, or post-process the JSON in your fetch script.
• Version lockstep. It is released in step with dreamfactory/dreamfactory. Bumping one without the other is a routine breakage; pin both and upgrade them together.
• Forking is a trap. If you need extra x- extensions or custom descriptions, add a thin decorator service or post-process the fetched spec. Forking means you own merge conflicts on every platform release.
• Debugging playbook. 90% of "the docs are wrong" resolves with three commands: php artisan route:list, a curl against the endpoint with an explicit X-DreamFactory-Api-Key (or session token), and a look at storage/logs/laravel.log. It is nearly always auth scope or cache — not the package.