PHPackages                             stacktrace/inspec - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. stacktrace/inspec

ActiveLibrary[API Development](/categories/api)

stacktrace/inspec
=================

OpenAPI scheme generator for Laravel APIs

0104—0%PHP

Since Apr 20Pushed 1w agoCompare

[ Source](https://github.com/stacktracelabs/inspec)[ Packagist](https://packagist.org/packages/stacktrace/inspec)[ RSS](/packages/stacktrace-inspec/feed)WikiDiscussions main Synced 4w ago

READMEChangelogDependenciesVersions (1)Used By (0)

stacktrace/inspec
=================

[](#stacktraceinspec)

`stacktrace/inspec` generates an OpenAPI 3 document from PHP attributes on Laravel controller actions and Fractal transformers.

It is route-aware at generation time: every documented operation is paired with a real Laravel route, so Inspec can infer methods, middleware, and auth from the framework route definition.

Installation
------------

[](#installation)

```
composer require stacktrace/inspec
```

How it works
------------

[](#how-it-works)

The package revolves around `StackTrace\Inspec\Api`, `StackTrace\Inspec\Documentation`, and `StackTrace\Inspec\OpenAPIDocument`.

```
use StackTrace\Inspec\Api;
use StackTrace\Inspec\Documentation;

class PublicApiDocumentation extends Documentation
{
    public function build(Api $api): void
    {
        $api
            ->name('public')
            ->title('Example API')
            ->description('Public API documentation')
            ->version('1.0.0')
            ->prefix('api')
            ->servers([
                'Production' => 'https://api.example.com',
                'Local' => 'http://localhost:8000/api',
            ])
            ->controllers(app_path('Http/Controllers/Api'))
            ->post(
                '/webhooks',
                tags: 'Webhooks',
                summary: 'Receive webhook deliveries',
                request: [
                    'event:string' => 'Webhook event name',
                ],
                response: [
                    'status:string' => 'Delivery status',
                ],
            );
    }
}

$api = new Api();
(new PublicApiDocumentation())->build($api);

$document = $api->toOpenAPI();

$yaml = $document->toYaml();
```

Generation currently works like this:

- `Documentation` classes configure an `Api` builder.
- `Api` scans the configured controller paths for public methods with `#[StackTrace\Inspec\Route(...)]`.
- Each annotated method must also be registered as a Laravel route. Unregistered methods are skipped.
- `Api` can also document existing Laravel routes directly with helpers like `post('/webhooks', ...)` or `route('webhooks.receive', ...)`.
- Manual route helpers also accept `operation: new \StackTrace\Inspec\Operation(...)` when you want to build or customize the route metadata explicitly.
- Invokable controllers are supported through `__invoke`.
- Transformer schemas are collected from `#[Schema(...)]` on the transformer's `transform()` method.
- Call `->prefix('api')` when Laravel routes are registered under `/api` but you want generated paths like `/users` instead of `/api/users`.
- Path filters always match the final generated path, so with `->prefix('api')` you should filter with `^/users`, not `^/api/users`.

Generate Command
----------------

[](#generate-command)

Configure the documentation classes in `config/inspec.php`:

```
return [
    'output' => 'openapi',
    'docs' => [
        App\OpenApi\PublicApiDocumentation::class,
    ],
];
```

Then generate all configured specs:

```
php artisan inspec:generate
```

Or generate one configured API by its `name()`:

```
php artisan inspec:generate --api=public
```

Or verify a single documentation class without rewriting files:

```
php artisan inspec:generate --api=App\\OpenApi\\PublicApiDocumentation --stdout
php artisan inspec:generate --api=public --stdout --path='^/users' --method=GET
php artisan inspec:generate --api=public --stdout --route=users.show
```

The `--path` option matches the final generated path after any `Api::prefix(...)` stripping.

Documenting Existing Laravel Routes
-----------------------------------

[](#documenting-existing-laravel-routes)

Not every route lives in a controller you can annotate. For package routes, closure routes, or third-party endpoints, configure them directly inside `build()`:

```