> ## 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.

# Installation

> Install Laravel OpenAPI Generator via Composer and configure your documentation settings

## Requirements

Before installing, ensure your environment meets these requirements:

| Component | Version             |
| --------- | ------------------- |
| PHP       | 8.1+                |
| Laravel   | 10.x, 11.x, or 12.x |
| Composer  | 2.x                 |

<Note>
  The package requires `illuminate/support`, `illuminate/console`, and `illuminate/routing` packages, which are included in standard Laravel installations.
</Note>

## Install via Composer

<Steps>
  <Step title="Require the package">
    Install the package using Composer:

    ```bash theme={null}
    composer require ronu/laravel-openapi-generator
    ```

    The service provider and facade are automatically discovered via Laravel's package auto-discovery feature defined in `composer.json`.
  </Step>

  <Step title="Verify installation">
    Confirm the package is installed by checking the available Artisan commands:

    ```bash theme={null}
    php artisan list openapi
    ```

    You should see the `openapi:generate` command listed.
  </Step>
</Steps>

## Publish Configuration Files

<Info>
  Publishing configuration files is **highly recommended** to customize API metadata, environments, and output settings.
</Info>

### Publish All Configuration Files

Run this command to publish all configuration files:

```bash theme={null}
php artisan vendor:publish --tag=openapi-config
```

This creates four configuration files in your `config/` directory:

<CodeGroup>
  ```php config/openapi.php theme={null}
  <?php

  return [
      'info' => [
          'title' => env('APP_NAME', 'Laravel API'),
          'description' => 'Complete API documentation for all application modules',
          'version' => env('API_VERSION', '1.0.0'),
      ],

      'servers' => [
          [
              'url' => 'http://127.0.0.1:8000',
              'description' => 'Artisan server',
          ],
      ],

      'api_types' => [
          'admin' => [
              'prefix' => 'admin',
              'folder_name' => 'API Admin',
              'enabled' => true,
          ],
      ],

      'output_path' => storage_path('app/public/openapi'),
  ];
  ```

  ```php config/openapi-docs.php theme={null}
  <?php

  return [
      // Custom endpoint documentation
      'custom_endpoints' => [],

      // Resource-specific documentation
      'resources' => [],
  ];
  ```

  ```php config/openapi-tests.php theme={null}
  <?php

  return [
      // Test script generation settings
      'enabled' => true,
      'assertions' => [],
  ];
  ```

  ```php config/openapi-templates.php theme={null}
  <?php

  return [
      // Template path configuration
      'path' => resource_path('openapi/templates'),
  ];
  ```
</CodeGroup>

### Configuration File Purposes

<CardGroup cols={2}>
  <Card title="openapi.php" icon="gear">
    Main configuration file for API metadata, servers, security schemes, API types, and output paths
  </Card>

  <Card title="openapi-docs.php" icon="book">
    Custom endpoint documentation and resource-specific descriptions that override auto-generated content
  </Card>

  <Card title="openapi-tests.php" icon="vial">
    Settings for Postman test script generation including assertions and variable tracking
  </Card>

  <Card title="openapi-templates.php" icon="file-code">
    Path configuration for custom JSON templates used to document specific endpoints
  </Card>
</CardGroup>

## Publish Templates (Optional)

If you want to customize endpoint documentation using JSON templates, publish the template directory:

```bash theme={null}
php artisan vendor:publish --tag=openapi-templates
```

This creates the template directory structure:

```
resources/openapi/templates/
├── users/
│   ├── index.json
│   ├── store.json
│   ├── show.json
│   ├── update.json
│   └── destroy.json
└── ...
```

<Warning>
  Templates are optional. If not provided, the generator will automatically extract metadata from FormRequests and models.
</Warning>

## Essential Configuration

After publishing, configure these essential settings in `config/openapi.php`:

### 1. API Information

Update the API metadata to match your application:

```php config/openapi.php theme={null}
'info' => [
    'title' => env('APP_NAME', 'My Laravel API'),
    'description' => 'Complete API documentation',
    'version' => env('API_VERSION', '1.0.0'),
    'contact' => [
        'name' => 'API Support',
        'email' => 'support@example.com',
    ],
],
```

### 2. API Servers

Define the environments where your API is accessible:

```php config/openapi.php theme={null}
'servers' => [
    [
        'url' => env('APP_URL', 'http://localhost:8000'),
        'description' => 'Local development server',
    ],
    [
        'url' => 'https://api.production.com',
        'description' => 'Production server',
    ],
],
```

### 3. API Types

Configure route prefixes for different API surfaces:

```php config/openapi.php theme={null}
'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'folder_name' => 'API Admin',
        'description' => 'Admin API - Backend management endpoints',
        'enabled' => true,
    ],
    'mobile' => [
        'prefix' => 'mobile',
        'folder_name' => 'API Mobile',
        'description' => 'Mobile API - Mobile application endpoints',
        'enabled' => true,
    ],
],
```

### 4. Security Schemes

Define authentication methods for your API:

```php config/openapi.php theme={null}
'security' => [
    'BearerAuth' => [
        'type' => 'http',
        'scheme' => 'bearer',
        'bearerFormat' => 'JWT',
        'description' => 'JWT Bearer Token authentication',
    ],
    'ApiKeyAuth' => [
        'type' => 'apiKey',
        'in' => 'header',
        'name' => 'X-API-Key',
        'description' => 'API Key authentication',
    ],
],
```

### 5. Route Exclusions

Exclude internal or framework routes from documentation:

```php config/openapi.php theme={null}
'exclude_routes' => [
    'api/documentation/*',
    'sanctum/*',
    '_ignition/*',
    'telescope/*',
    'horizon/*',
],
```

## Enable HTTP Documentation Routes

To serve documentation via HTTP endpoints, ensure routes are enabled:

```php config/openapi.php theme={null}
'routes' => [
    'enabled' => env('OPENAPI_ROUTES_ENABLED', true),
    'prefix' => env('OPENAPI_ROUTES_PREFIX', 'documentation'),
    'middleware' => [],
],
```

With this configuration, documentation is accessible at:

* `http://localhost:8000/documentation/openapi.json`
* `http://localhost:8000/documentation/openapi.yaml`
* `http://localhost:8000/documentation/postman`
* `http://localhost:8000/documentation/insomnia`

<Warning>
  In production, protect documentation routes with authentication middleware to prevent public access to your API structure.
</Warning>

## Environment Variables

For sensitive or environment-specific settings, use `.env` variables:

```bash .env theme={null}
APP_NAME="My Application API"
API_VERSION="2.0.0"
API_CONTACT_EMAIL="api@example.com"

OPENAPI_ROUTES_ENABLED=true
OPENAPI_ROUTES_PREFIX=documentation
OPENAPI_CACHE_ENABLED=true
OPENAPI_CACHE_TTL=3600
```

## Optional: Modular Architecture Support

If you use [Nwidart Laravel Modules](https://github.com/nWidart/laravel-modules), configure the modules path:

```php config/openapi.php theme={null}
'modules_path' => base_path('Modules'),

'paths' => [
    'models' => [
        'App\\Models',
        'Modules\\{module}\\Entities',
    ],
    'requests' => [
        'App\\Http\\Requests',
        'Modules\\{module}\\Http\\Requests',
    ],
],
```

The `{module}` placeholder is automatically replaced with actual module names during generation.

## Verify Installation

Test the installation by generating documentation:

```bash theme={null}
php artisan openapi:generate
```

If successful, you'll see output files in the configured output directory (default: `storage/app/public/openapi/`).

## Next Steps

<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
  Generate your first complete API documentation with a step-by-step tutorial
</Card>