filament-openapi-docs

KO | EN

gitlite — search

#rag #chatbot #deep-learning #c #swift #go #android #claude-code #anthropic #java

filament-openapi-docs

(★ 9)

Native Filament panel page for browsing Scramble-powered OpenAPI documentation and testing API endpoints directly from your dashboard

File Explorer

ZIP Download

- dependabot.yml
- FUNDING.yml
- SECURITY.md
- build.js
- filament-openapi-docs.php
- - filament-openapi-docs-http-snippet.png
  - filament-openapi-docs-page.png
  - filament-openapi-docs-request-auth.png
  - filament-openapi-docs-request-sent.png
  - filament-openapi-docs-request.png
  - filament-openapi-docs-responses.png
- screenshots.md
- - openapi-docs.css
- - request-snippet.js
- - openapi-docs.blade.php
- - Endpoint.php
- - HttpMethod.php
- - OpenApiDocsPage.php
- - ExamplePresenter.php
  - OpenApiDataResolver.php
  - OpenApiNavigationBuilder.php
  - OpenApiParser.php
  - RequestSnippetPresenter.php
  - SchemaPresenter.php
- - HttpStatus.php
  - ScrambleSpecProvider.php
  - SpecProvider.php
  - VersionedSpecProvider.php
- FilamentOpenApiDocsPlugin.php
- FilamentOpenApiDocsServiceProvider.php
- - FilamentOpenApiDocsPluginTest.php
  - OpenApiParserTest.php
  - SchemaPresenterTest.php
  - ScrambleSpecProviderTest.php
- bootstrap.php
- Pest.php
- TestCase.php
.gitattributes
.gitignore
.prettierrc
composer.json
composer.lock
LICENSE
package.json
phpstan.neon
phpunit.xml
pint.json
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Latest Version on Packagist Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Laravel](https://img.shields.io/badge/Laravel-11%20%7C%2012%20%7C%2013-red?logo=laravel&logoColor=white)]()
[![Filament](https://img.shields.io/badge/Filament-4%20%7C%205-FFA500?logo=filament&logoColor=white)]()
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]()
[![License](https://img.shields.io/badge/license-MIT-green)](https://raw.githubusercontent.com/alexkramse/filament-openapi-docs/main/LICENSE.md)

## Introduction

A Native [`Filament`](https://filamentphp.com/) plugin for OpenAPI documentation powered by [`Scramble`](https://scramble.dedoc.co/).
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 multiple API's version selector or dedicated version-specific docs pages.
- 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.

![Filament OpenAPI docs page](https://raw.githubusercontent.com/alexkramse/filament-openapi-docs/main/docs/images/filament-openapi-docs-page.png)
More screenshots are available in [docs/screenshots.md](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`](https://scramble.dedoc.co/) 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:

```bash
composer require alexkramse/filament-openapi-docs
```

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

```bash
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
<?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:

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

Panel-level fluent configuration overrides the config file:

```php
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')
    ->versions(['v1', 'v2']);
```

`versions()` accepts the aliases registered with `Scramble::registerApi()`. A page with multiple aliases shows a version selector. To show one version on a dedicated docs page, use `->version('v2')`. When neither option is configured, the plugin discovers all named Scramble APIs automatically. If only Scramble's `default` API exists, the plugin keeps the existing single-document behavior and uses `->scrambleGenerator('default')`.

```php
FilamentOpenApiDocsPlugin::make('api-v2')
    ->slug('developer/api-docs-v2')
    ->navigationLabel('OpenAPI v2')
    ->version('v2');
```

Use a unique plugin ID when registering more than one docs page.

### 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.              |
| `versions()`              | —                                | Explicitly lists named Scramble APIs for a version selector. |
| `version()`               | —                                | Restricts this docs page to one Scramble API.      |

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:

```env
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:

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

Published files are placed in:

```text
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`:

```php
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`:

```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:

```bash
php artisan filament:assets
```

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

```bash
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:

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

## Support

If this package helps you, consider supporting its development:

- ⭐ Give the repository a [star on GitHub](https://github.com/alexkramse/filament-openapi-docs) — it helps other developers discover the package.
- ☕ [Buy me a coffee](https://www.buymeacoffee.com/alexkramse) — a small thank you for the time spent maintaining the package.
- 💖 [Become a GitHub sponsor](https://github.com/sponsors/alexkramse) — sponsor the ongoing development of this and other open source projects.

Bug reports and feature requests are welcome in the [issue tracker](https://github.com/alexkramse/filament-openapi-docs/issues).

## 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](https://www.linkedin.com/in/oleksandrkramarenko)

## License

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

filament-openapi-docs

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README