> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/charlietyn/openapi-generator/llms.txt
> Use this file to discover all available pages before exploring further.

# Middleware

> Middleware configuration for HTTP documentation routes

## Overview

The Laravel OpenAPI Generator does not include custom middleware classes. Instead, it provides configuration options to apply your existing Laravel middleware to the HTTP documentation routes.

<Note>
  HTTP routes are only available when `openapi.routes.enabled` is set to `true` in the configuration.
</Note>

***

## Configuration

### Route Middleware

Configure middleware for the documentation routes in `config/openapi.php`:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web'], // Apply middleware here
],
```

**Location:** `config/openapi.php`

***

## Common Middleware Patterns

### Public Access (Default)

No authentication required - suitable for public APIs:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web'],
],
```

***

### Authenticated Access (Sanctum)

Require authentication via Laravel Sanctum:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['auth:sanctum'],
],
```

**Usage:**

Users must provide a valid token to access documentation:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/documentation/openapi.json
```

***

### Session Authentication

Require authenticated session (for web-based access):

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'auth'],
],
```

***

### Admin-Only Access

Restrict access to admin users:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['auth:sanctum', 'admin'], // Assuming you have an 'admin' middleware
],
```

**Example Admin Middleware:**

```php theme={null}
// app/Http/Middleware/EnsureUserIsAdmin.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class EnsureUserIsAdmin
{
    public function handle(Request $request, Closure $next)
    {
        if (!$request->user() || !$request->user()->is_admin) {
            abort(403, 'Access denied');
        }

        return $next($request);
    }
}
```

Register in `app/Http/Kernel.php`:

```php theme={null}
protected $middlewareAliases = [
    // ...
    'admin' => \App\Http\Middleware\EnsureUserIsAdmin::class,
];
```

***

### IP Whitelist

Restrict access to specific IP addresses:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'ip.whitelist'],
],
```

**Example IP Whitelist Middleware:**

```php theme={null}
// app/Http/Middleware/IpWhitelist.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class IpWhitelist
{
    protected array $whitelist = [
        '127.0.0.1',
        '::1',
        // Add your allowed IPs
    ];

    public function handle(Request $request, Closure $next)
    {
        if (!in_array($request->ip(), $this->whitelist)) {
            abort(403, 'Access denied from your IP address');
        }

        return $next($request);
    }
}
```

***

### Environment-Based Access

Allow access only in development environments:

```php theme={null}
'routes' => [
    'enabled' => env('APP_ENV') !== 'production',
    'prefix' => 'documentation',
    'middleware' => ['web'],
],
```

Or use middleware:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'dev.only'],
],
```

**Example Development-Only Middleware:**

```php theme={null}
// app/Http/Middleware/DevelopmentOnly.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class DevelopmentOnly
{
    public function handle(Request $request, Closure $next)
    {
        if (!app()->environment(['local', 'development'])) {
            abort(404);
        }

        return $next($request);
    }
}
```

***

### API Key Authentication

Require an API key in request headers:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'api.key'],
],
```

**Example API Key Middleware:**

```php theme={null}
// app/Http/Middleware/ValidateApiKey.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class ValidateApiKey
{
    public function handle(Request $request, Closure $next)
    {
        $apiKey = $request->header('X-API-Key');
        $validKey = config('services.docs.api_key');

        if ($apiKey !== $validKey) {
            return response()->json([
                'error' => 'Invalid or missing API key'
            ], 401);
        }

        return $next($request);
    }
}
```

**Usage:**

```bash theme={null}
curl -H "X-API-Key: your-secret-key" \
  http://localhost:8000/documentation/openapi.json
```

***

## Available Routes

All these routes respect the configured middleware:

| Route                                   | Method | Description                 |
| --------------------------------------- | ------ | --------------------------- |
| `/documentation/openapi.{format}`       | GET    | Generate OpenAPI spec       |
| `/documentation/postman`                | GET    | Generate Postman collection |
| `/documentation/insomnia`               | GET    | Generate Insomnia workspace |
| `/documentation/environments/{format?}` | GET    | Get all environments        |

**Route Configuration Location:**

Routes are registered in the service provider when `routes.enabled` is `true`.

***

## Security Middleware Mapping

### OpenAPI Security Schemes

The package also allows you to map middleware to OpenAPI security schemes for route documentation:

```php theme={null}
// config/openapi.php
'middleware_security_map' => [
    'auth:sanctum' => ['BearerAuth'],
    'auth:api' => ['ApiKeyAuth'],
    'signed' => ['SignedUrl'],
],
```

**How It Works:**

When generating OpenAPI specs, routes with these middleware automatically include the appropriate security requirements in the documentation.

**Example:**

If a route has `auth:sanctum` middleware:

```php theme={null}
Route::middleware(['auth:sanctum'])
    ->get('/api/users', [UserController::class, 'index']);
```

The OpenAPI spec will include:

```json theme={null}
{
  "paths": {
    "/api/users": {
      "get": {
        "security": [
          {"BearerAuth": []}
        ]
      }
    }
  }
}
```

**Security Scheme Definitions:**

Define the schemes in your configuration:

```php theme={null}
'components' => [
    'securitySchemes' => [
        'BearerAuth' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
        ],
        'ApiKeyAuth' => [
            'type' => 'apiKey',
            'in' => 'header',
            'name' => 'X-API-Key',
        ],
    ],
],
```

**Location:** `src/Services/OpenApiServices.php:1310-1327`

***

## Rate Limiting

Apply rate limiting to documentation routes:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'throttle:60,1'], // 60 requests per minute
],
```

**Custom Rate Limiter:**

```php theme={null}
// app/Providers/RouteServiceProvider.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

public function boot()
{
    RateLimiter::for('docs', function (Request $request) {
        return Limit::perMinute(30)->by($request->ip());
    });
}
```

Then in configuration:

```php theme={null}
'middleware' => ['web', 'throttle:docs'],
```

***

## CORS Configuration

If you need to allow cross-origin requests to documentation routes:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['web', 'cors'],
],
```

**CORS Configuration:**

```php theme={null}
// config/cors.php
return [
    'paths' => ['documentation/*'],
    'allowed_methods' => ['GET', 'POST'],
    'allowed_origins' => ['*'],
    'allowed_headers' => ['*'],
    'max_age' => 3600,
];
```

***

## Middleware Groups

Create a custom middleware group for documentation:

```php theme={null}
// app/Http/Kernel.php
protected $middlewareGroups = [
    'docs' => [
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Session\Middleware\StartSession::class,
        'auth:sanctum',
        'throttle:60,1',
    ],
];
```

Use in configuration:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => ['docs'],
],
```

***

## Disabling HTTP Routes

If you prefer to generate specifications only via Artisan commands and not expose HTTP endpoints:

```php theme={null}
'routes' => [
    'enabled' => false,
],
```

This completely disables route registration. Use the [Artisan command](/api-reference/artisan-commands) or [Public API](/api-reference/public-api) instead.

***

## Testing Middleware

### Feature Test Example

```php theme={null}
// tests/Feature/OpenApiRoutesTest.php
namespace Tests\Feature;

use Tests\TestCase;

class OpenApiRoutesTest extends TestCase
{
    /** @test */
    public function unauthenticated_users_cannot_access_documentation()
    {
        $response = $this->get('/documentation/openapi.json');

        $response->assertStatus(401);
    }

    /** @test */
    public function authenticated_users_can_access_documentation()
    {
        $user = User::factory()->create();

        $response = $this->actingAs($user, 'sanctum')
            ->get('/documentation/openapi.json');

        $response->assertStatus(200);
        $response->assertHeader('Content-Type', 'application/json');
    }

    /** @test */
    public function admin_users_can_access_documentation()
    {
        $admin = User::factory()->admin()->create();

        $response = $this->actingAs($admin, 'sanctum')
            ->get('/documentation/openapi.json');

        $response->assertStatus(200);
        $response->assertJsonStructure(['openapi', 'info', 'paths']);
    }
}
```

***

## Best Practices

<Tip>
  **Production Environments:**

  * Always require authentication for documentation routes in production
  * Consider IP whitelisting for internal tools
  * Apply rate limiting to prevent abuse
  * Use HTTPS for all documentation endpoints
</Tip>

<Tip>
  **Development Environments:**

  * Use minimal middleware for easy access during development
  * Consider enabling routes only in non-production environments
  * Use `.env` variables to control route availability
</Tip>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="HTTP Routes" icon="globe" href="/guides/basic-usage">
    Configure HTTP documentation endpoints
  </Card>

  <Card title="Artisan Commands" icon="terminal" href="/api-reference/artisan-commands">
    Generate docs via CLI
  </Card>

  <Card title="Security" icon="shield" href="/guides/security">
    Security best practices
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/reference">
    Full configuration reference
  </Card>
</CardGroup>