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.
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.3
Laravel ^13.0
Filament ^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 English (en), Ukrainian (uk), German (de), Spanish (es), and French (fr). It uses Laravel's current locale and fallback locale, so you may switch languages with your normal application configuration:

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 translation, create a new locale directory such as lang/vendor/filament-openapi-docs/pl/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.
Assets are registered under the package name alexkramse/filament-openapi-docs.

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.

Before enabling request testing in production, confirm that:

the Filament panel is protected by the right authentication and authorization rules;
the configured API server is safe for dashboard users to call;
CORS, cookies, CSRF behavior, and API authentication are configured intentionally;
sensitive production endpoints should be exposed only to users who are allowed to test them.

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

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

License

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

alexkramse / filament-openapi-docs

Maintainers

Package info

Fund package maintenance!

Statistics

Security