README

Introduction

A Native Filament plugin for OpenAPI documentation powered by Scramble. Filament OpenAPI Docs adds a dashboard page to your Filament panel where authenticated dashboard users can browse your generated OpenAPI specification, inspect endpoints, view request examples, and test API calls without leaving the admin area.

Features

Adds a native Filament page inside your existing panel navigation.
Reads the generated OpenAPI document from Scramble by default.
Groups endpoints in Filament sub-navigation for fast browsing.
Shows endpoint methods, paths, parameters, request bodies, responses, schemas, and examples.
Generates request samples for multiple languages and clients.
Lets users test API endpoints directly from the dashboard.
Provides configurable developer mode for custom request headers and query parameters.
Supports panel-level fluent configuration and a publishable config file.
Ships UI translations for all 62 locales supported by Filament Panels.
Registers package CSS and JavaScript through Filament's asset manager.

Screenshots

Filament-native OpenAPI docs page with endpoint navigation, request documentation, request samples, and responses.

More screenshots are available in docs/screenshots.md.

Requirements

PHP ^8.2
Laravel ^11.28 || ^12.0 || ^13.0
Filament ^4.0 || ^5.0
dedoc/scramble ^0.13.30

This package currently requires dedoc/scramble and is tested only with Scramble-generated OpenAPI documents. Scramble is installed as a package dependency, but your Laravel application still needs a working Scramble configuration so the OpenAPI document can be generated correctly.

Installation

Install the package with Composer:

composer require alexkramse/filament-openapi-docs

Publish Filament assets so the package CSS and async Alpine component are available in the browser:

php artisan filament:assets

You should also run php artisan filament:assets after package updates and during deployment if your application does not already run Filament's asset upgrade command automatically.

Register The Plugin

<?php

namespace App\Providers\Filament;

use Alexkramse\FilamentOpenapiDocs\FilamentOpenApiDocsPlugin;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            // ...
            ->plugin(FilamentOpenApiDocsPlugin::make());
    }
}

The default page slug is api-docs. For example, if your panel is available at /admin, the documentation page will be available at /admin/api-docs.

Access is handled by your Filament panel. Users must pass the same authentication, middleware, and authorization rules that protect the panel.

Usage

After registration, open your Filament dashboard and select the API Docs navigation item.

The page displays your OpenAPI document as a Filament-native interface:

the page title and description come from plugin configuration, config, or OpenAPI info;
endpoint groups are shown in the page sub-navigation;
selecting an endpoint updates the URL query string so links can be shared inside the team;
request parameters, body examples, response schemas, and examples are rendered from the OpenAPI specification.

When request samples are enabled, each endpoint includes generated request snippets and a request sender. The request sender sends requests from the browser, so the selected server URL, CORS rules, cookies, and API authentication must allow the request.

Developer mode is available inside the request sender when developer options are enabled. It allows trusted dashboard users to add custom headers and query parameters before sending a request.

Security, headers, query parameters, body, and path parameters remain visible as request sections regardless of developer mode. Developer mode only controls the advanced add/edit controls for custom headers and query parameters.

Configuration

You may publish the config file:

php artisan vendor:publish --tag=filament-openapi-docs-config

Panel-level fluent configuration overrides the config file:

use Alexkramse\FilamentOpenapiDocs\FilamentOpenApiDocsPlugin;

FilamentOpenApiDocsPlugin::make()
    ->slug('developer/api-docs')
    ->navigationLabel('OpenAPI')
    ->navigationIcon('heroicon-o-document-text')
    ->navigationGroup('Developer')
    ->navigationSort(100)
    ->navigationBadge('count')
    ->navigationBadgePrefix('')
    ->navigationBadgeSuffix(' endpoints')
    ->subNavigationPosition('right')
    ->title('API Documentation')
    ->description('Browse and test available API endpoints.')
    ->enabledInProduction()
    ->fullWidth()
    ->requestSamples()
    ->developerOptions()
    ->defaultServer('https://api.example.com')
    ->scrambleGenerator('default');

Available Options

Method	Config key	Description
`slug()`	`slug`	Changes the Filament page slug.
`navigationLabel()`	`navigation.label`	Changes the navigation label.
`navigationIcon()`	`navigation.icon`	Changes the navigation icon.
`navigationGroup()`	`navigation.group`	Places the page in a navigation group.
`navigationSort()`	`navigation.sort`	Controls navigation ordering.
`navigationBadge()`	`navigation.badge`	Shows `version`, `count`, or no badge with `null`.
`navigationBadgePrefix()`	`navigation.badge_prefix`	Adds text before the badge value.
`navigationBadgeSuffix()`	`navigation.badge_suffix`	Adds text after the badge value.
`subNavigationPosition()`	`sub_navigation.position`	Uses `left` or `right` endpoint navigation.
`title()`	`page.title`	Overrides the page title.
`description()`	`page.description`	Overrides the page description.
`enabledInProduction()`	`page.enabled_in_production`	Registers the docs page in production.
`fullWidth()`	`layout.full_width`	Uses Filament's full-width page layout.
`requestSamples()`	`request_samples.enabled`	Enables or disables snippets and request testing.
`developerOptions()`	`request_samples.developer_options`	Enables developer mode for custom headers and query parameters.
`defaultServer()`	`request_samples.default_server`	Sets the default server for generated requests.
`scrambleGenerator()`	`scramble.generator`	Selects the Scramble generator name.

Supported navigation badge modes are version, count, and null.

The docs page is hidden in production by default. Enable page.enabled_in_production or call enabledInProduction() only when trusted production panel users should be able to access API documentation.

Developer options are disabled by default. Enable them when dashboard users should be able to toggle developer mode and add or edit custom request headers and query parameters.

Translations

The package ships with UI translations for all 62 locales currently shipped by Filament Panels. It uses Laravel's current locale and fallback locale.

Supported Locales

The package supports the following locale codes:

am, ar, az, bg, bn, bs, ca, ckb, cs, da, de, el, en, es, et, eu, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, km, ko, ku, lt, lus, lv, mk, mn, ms, my, nb, ne, nl, pl, pt, pt_BR, ro, ru, sk, sl, sq, sr_Cyrl, sr_Latn, sv, sw, th, tr, uk, ur, uz, vi, zh_CN, zh_HK, and zh_TW.

If a translation is unavailable in the active locale, Laravel resolves it through APP_FALLBACK_LOCALE.

Switching the Active Locale

For example, configure Ukrainian as the active locale and English as its fallback:

APP_LOCALE=uk
APP_FALLBACK_LOCALE=en

OpenAPI content from your specification, such as endpoint summaries, descriptions, schemas, examples, and server URLs, is rendered as provided by the specification.

Customize Package Translations

Publish the translation files when you want to customize labels or add your own locale:

php artisan vendor:publish --tag=filament-openapi-docs-translations

Published files are placed in:

lang/vendor/filament-openapi-docs/{locale}/ui.php

To add a new locale, create a directory such as lang/vendor/filament-openapi-docs/eo/ui.php, copy the structure from resources/lang/en/ui.php, and translate only the values. Keep the array keys unchanged.

To update local overrides after a package upgrade, compare the newest package resources/lang/en/ui.php file with your files in lang/vendor/filament-openapi-docs/{locale}/ui.php and copy any missing keys. Use vendor:publish --tag=filament-openapi-docs-translations --force only when you intentionally want to replace local customizations.

Custom Spec Providers

Scramble is the supported and tested OpenAPI source. If you need to load a specification from another source, you may bind a custom provider through the config file, but non-Scramble providers are not tested by this package yet.

Your provider must implement Alexkramse\FilamentOpenapiDocs\Support\SpecProvider:

use Alexkramse\FilamentOpenapiDocs\Support\SpecProvider;
use Dedoc\Scramble\GeneratorConfig;

class CustomSpecProvider implements SpecProvider
{
    public function config(): GeneratorConfig
    {
        // Return the generator config used by the docs renderer.
    }

    public function view(): string
    {
        // Return the renderer view name used by the spec provider.
    }

    public function spec(): array
    {
        // Return the OpenAPI document as an array.
    }
}

Then update config/filament-openapi-docs.php:

'provider' => CustomSpecProvider::class,

Assets

The package follows Filament's asset manager conventions:

CSS is registered with loadedOnRequest() and is only loaded when requested by the OpenAPI docs page.
The request sender is registered as an asynchronous Alpine component.

For application installation and deployment, run:

php artisan filament:assets

For local package development, rebuild package assets after changing files in resources/js or resources/css:

npm install
npm run build

You do not need to run npm run build in a consuming Laravel application unless you are developing this package locally or changing its frontend source files.

Security Notes

This package is intended for trusted dashboard users. The request sender can send custom headers, parameters, auth values, and request bodies from the browser.

You can disable request samples and request testing while keeping the documentation page:

FilamentOpenApiDocsPlugin::make()
    ->requestSamples(false);

Support

If this package helps you, consider supporting its development:

⭐ Give the repository a star on GitHub — it helps other developers discover the package.
☕ Buy me a coffee — a small thank you for the time spent maintaining the package.
💖 Become a GitHub sponsor — sponsor the ongoing development of this and other open source projects.

Bug reports and feature requests are welcome in the issue tracker.

About Me

Senior Laravel and Full-Stack Developer focused on building applications from scratch, modernizing legacy systems, and creating practical solutions that improve business operations.

I like a pragmatic approach to well-optimized code, efficient database queries, use coding best practices and principles.

Available now for remote full-time, part-time, and freelance opportunities in Laravel, PHP, Filament, API development, backend engineering, and application modernization.

If you need someone to build, maintain, modernize, and evolve production-ready software, I’d be glad to connect.

LinkedIn: Connect with me on LinkedIn

License

The MIT License (MIT). Please see License File for more information.

alexkramse / filament-openapi-docs

Maintainers

Package info

Fund package maintenance!

Statistics

Security