Knuckleswtf Scribe: generating readable API docs from a Laravel codebase

What Scribe reads out of a Laravel app

The README describes Scribe as generating API documentation for humans from a Laravel codebase, and the feature list is more informative than that one-liner. The package can extract request parameter details from FormRequests or from validation rules, which means the documentation for a `POST /users` endpoint reflects the rules that endpoint already enforces. It can safely call API endpoints to collect sample responses, and it can generate those responses from Eloquent API Resources or Transformers without issuing a request at all.

That third option is the one worth pausing on. Generating a sample response from the resource class rather than by calling the endpoint avoids needing seeded data, a working third-party service, or a database, which is the usual reason a docs generator produces empty example payloads. It also means the example is structurally accurate and semantically fictional, which is usually the right trade for documentation.

A live example is hosted at demo.scribe.knuckles.wtf, and the documentation site is at scribe.knuckles.wtf/laravel. The package sits on Packagist as knuckleswtf/scribe under the MIT license, with 2,337 stars. The default branch is `v5`, which tells you the current major line is 5 even though the release tags carry no `v` prefix.

Three output formats, and only one of them is for people

Scribe produces a single-page HTML document with human-friendly text, code samples, and an in-browser API tester called Try It Out. It also produces a Postman collection and an OpenAPI spec, at either version 3.0.3 or 3.1.0.

The distinction matters because the three outputs have different audiences and different failure modes. The HTML page is for whoever reads the docs. The Postman collection is for a developer who wants to click through endpoints, and it inherits whatever example values the HTML shows. The OpenAPI spec is for code generators and client SDK tooling, where a malformed example is more expensive than a slightly ugly one.

Choosing between OpenAPI 3.0.3 and 3.1.0 is a real decision rather than a formality, since the two differ in how they express nullable types and schema composition. The README offers the choice without explaining when each is preferable, which means you will be picking based on what your consumers can parse. If client generators are the consumers, check whether the tooling you use handles 3.1.0 before opting into it.

The customization options are described in one short list: adjust text, ordering and examples, change the UI itself, add custom strategies to alter how data is extracted, and statically declare endpoints or information that do not exist in your code. That last one is how you document a webhook you do not own or an endpoint that is served by another team.

An honest caveat from the maintainer, and what it implies

The README contains a callout that says Scribe generates documentation automatically, but that making friendly, maintainable and testable API documentation requires more than generation, and it links to a paid course on the subject. This is worth taking at face value rather than reading as marketing, because it describes the actual boundary of the tool.

Generated documentation inherits the structure of your codebase and none of its editorial judgment. It will faithfully show that an endpoint takes four optional parameters and returns a 200 with a JSON body. It will not tell a reader what the endpoint is for, which errors are expected, or what a sensible retry looks like. It also cannot tell whether your endpoint names are good, because it reports them rather than evaluating them.

The customization hooks are the answer to that limit, and they are more powerful than the README's brevity suggests. A custom strategy lets you substitute your own logic for how a given piece of data is extracted, which is how you attach descriptions, mark a parameter deprecated, or supply an example the generator cannot infer. If a generated page reads poorly, the fix is almost always a strategy or a static override rather than a switch in the config.

Release history shows what actually breaks

Three recent releases tell you more about the maintenance pattern than any statement of intent would. Version 5.11.0 on 2026-06-08 fixes nested BelongsTo relationship loading in the response-from-API-Resource path, stops pre-URL-encoding query keys and values in the generated Postman collection, and updates the description used for the `exists` validation rule.

The Postman fix is the interesting one for consumers. Pre-encoding a query parameter twice produces a collection that looks fine in the file and then sends the wrong request, so this is a bug that would have been reported as a Scribe problem by someone whose application was fine.

Version 5.10.0, from 2026-05-09, adds an `afterExtracting` hook for modifying endpoint data after extraction, allows Blade syntax in the `base_url` config, moves the `required` flag from array schema to object schema inside `items`, and handles a null example in an array body parameter. Two of those four are OpenAPI correctness fixes, which suggests the spec output has been the source of a steady trickle of reports.

Version 5.9.0 from 2026-03-21 is a single change: support for symfony/yaml v8. Dependency maintenance, in other words. The last push was 2026-08-13, roughly two months after that release.

The repository layout and how to work on the generator itself

The tree gives a fairly clear picture of a package that ships more than a library. There is `src/` for the implementation, `config/` for configuration, `resources/` for views, `routes/` for its own routes, and `lang/` for translations. Two directories are less conventional: `camel/`, whose purpose is not documented in the README, and `.agents/`, joined by an `AGENTS.md` at the root.

Testing is set up three ways at once. There is a `phpunit.xml`, a `phpstan.neon` for static analysis, and a `pint.json`, with the README badge pointing at Laravel Pint as the code style tool. There is also a `Dockerfile`, a `docker-compose.yml`, and a `Makefile`, which together give you a containerized path for running the suite. The Makefile keeps the steps in one line:

test: install lint-ci test-ci

The container's entry comment tells you the intended invocation, which is also the compose file's command:

docker-compose up -d && docker logs -f scribe_app_1

The image is Ubuntu jammy with the PHP extensions the suite needs, including pcov for coverage, pdo and sqlite3 for the database, and imagick and gd for image handling. Nothing in the README explains the `camel/` directory or the AGENTS.md file, so if you are contributing rather than consuming, those are the first two things to ask about in the contribution guide at scribe.knuckles.wtf/laravel/contributing.

Editorial conclusion

Scribe is at its best when it stays inside the framework's own conventions. If your validation lives in FormRequests and your response shaping lives in API Resources, the generated examples are close to what a colleague would have written by hand. It is at its worst when you want prose, because it will not write prose for you, and the author says as much in a callout recommending a separate course on writing maintainable API documentation. Concretely, the README has no install command at all, so the first real step is the documentation site at scribe.knuckles.wtf, and the useful decisions live there: which strategies you enable, whether the built-in API tester is exposed, and whether the OpenAPI output targets 3.0.3 or 3.1.0. Start with a single resource route, generate, and read the output before pointing the generator at the whole surface.

Frequently asked questions

Official sources

1. knuckleswtf/scribe on GitHub
2. License: MIT
3. Project website
4. README
5. Releases