Introducing Fabric: an API reference UI built for Laravel

Introducing Fabric: an API reference UI built for Laravel

Published

Introducing Fabric, the API reference UI built for Laravel, with guides, nested navigation, search, and examples.

Since the beginning of Scramble, I’ve received requests related to the API reference UI and couldn’t really do much about them because Scramble relied on other libraries to render the UI.

These include guides alongside the endpoint reference, nested navigation, search, etc. Some of these requests, like search, were addressed by adding new renderers, Scalar in particular. But nested navigation and guides were still unsolved problems.

Besides navigation and guides, generic OpenAPI UI renderers are not “aware” that the OpenAPI spec they render describes a Laravel API. This makes some things tricky, especially nested query parameters and optional path parameters.

Meet Fabric – the API reference UI built for Laravel. It supports guides, nested navigation, search, and examples, and is designed to make your API easier to understand and use.

Read the Fabric docs · Open the demo

Fabric in light mode showing the List companies endpoint, navigation, query parameters, and request and response examples.

Here is a quick look at Fabric’s capabilities.

Guides

Existing API reference UIs allow you to see endpoint and schema documentation. But usually this is not enough: you may want to document how pagination works, common errors, rate limiting, authentication details, etc. This is what guides are for – additional information you want your API consumers to know.

Guides can be placed at the top level or grouped together with endpoints, within their groups, allowing you to explain details specific to those endpoints.

Fabric displaying a guide alongside the API reference navigation.

Nested navigation

With OpenAPI 3.2 (which, by the way, Scramble now supports!), tags can be organized into nested levels: one tag can belong to another. Fabric renders this kind of navigation, allowing you to organize endpoints however deeply you need.

Fabric also supports another kind of nested navigation – sections. Using sections, you can split your API reference into separate blocks. This is useful when your API can be clearly separated into different concepts (or even different APIs!).

Nested endpoint groups in Fabric's navigation.
Nested endpoint groups in Fabric's navigation.
Fabric navigation divided into sections.
Fabric navigation divided into sections.

With search, your API consumers can quickly find an endpoint they’re looking for or a guide.

Fabric search in light mode.

Optional path parameters

Laravel routes can have optional path parameters:

// routes/api.php
Route::get('projects/{projectId}/activity/{period?}', function (string $projectId, string $period = 'week') { /* ... */ });

OpenAPI requires path parameters to be marked as required. Scramble adds x-optional to preserve Laravel’s optional route parameters, and Fabric uses it to display GET /projects/{projectId}/activity/{period?}.

Query parameter serialization

Laravel accepts nested query parameters using bracket notation. For example, a request can filter projects by both their ID and status:

GET /projects/filter?filter[0][id][_eq]=42&filter[1][status][_eq]=active

Laravel parses filter into a nested PHP array, including the _eq conditions above.

OpenAPI’s standard deepObject serialization doesn’t define how to encode nested objects and arrays. Scramble adds the x-deepObject-style: qs extension to describe Laravel’s bracket notation, and Fabric uses it when generating request examples.

The Bash example produces a URL with the bracketed names percent-encoded, while the Laravel example passes the same filters as a nested PHP array to the HTTP client. Your API consumers get examples that match how Laravel reads their query parameters.

Examples

Fabric provides examples for API requests (Bash and Laravel at the moment), request schemas, and responses.

For reusable schemas, Fabric also generates TypeScript types ready to copy and use in your project.

Fabric displaying generated TypeScript types for a reusable schema.

What’s next

I’m excited to build a “Try it out” feature and would like to develop it with someone who needs it. If you’d like to try it and share feedback during development, let me know on Discord.

More request languages and HTTP clients are planned, too.

Try Fabric now

To try Fabric, update Scramble to at least 0.13.53, then set scramble.renderer to fabric:

'renderer' => 'fabric',

Learn more about Fabric.


Give Fabric a try and let me know what you think!

Scramble PRO
Comprehensive API documentation generation for Spatie’s Laravel Data, Laravel Query Builder, and other packages.