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

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

Install via Composer

1. Require the package

   Install the package using Composer:

   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.

2. Verify installation

   Confirm the package is installed by checking the available Artisan commands:

   php artisan list openapi
   

   You should see the openapi:generate command listed.

Publish Configuration Files

Publishing configuration files is highly recommended to customize API metadata, environments, and output settings.

Publish All Configuration Files

Run this command to publish all configuration files:

php artisan vendor:publish --tag=openapi-config

This creates four configuration files in your config/ directory:

config/openapi.php

<?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'),
];

Configuration File Purposes

openapi.php

Main configuration file for API metadata, servers, security schemes, API types, and output paths

openapi-docs.php

Custom endpoint documentation and resource-specific descriptions that override auto-generated content

openapi-tests.php

Settings for Postman test script generation including assertions and variable tracking

openapi-templates.php

Path configuration for custom JSON templates used to document specific endpoints

Publish Templates (Optional)

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

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
└── ...

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

Essential Configuration

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

1. API Information

Update the API metadata to match your application:

config/openapi.php

'info' => [
    'title' => env('APP_NAME', 'My Laravel API'),
    'description' => 'Complete API documentation',
    'version' => env('API_VERSION', '1.0.0'),
    'contact' => [
        'name' => 'API Support',
        'email' => '[e-mail]',
    ],
],

2. API Servers

Define the environments where your API is accessible:

config/openapi.php

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

config/openapi.php

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

config/openapi.php

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

config/openapi.php

'exclude_routes' => [
    'api/documentation/*',
    'sanctum/*',
    '_ignition/*',
    'telescope/*',
    'horizon/*',
],

Enable HTTP Documentation Routes

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

config/openapi.php

'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

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

Environment Variables

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

.env

APP_NAME="My Application API"
API_VERSION="2.0.0"
API_CONTACT_EMAIL="[e-mail]"

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, configure the modules path:

config/openapi.php

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

php artisan openapi:generate

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

Next Steps

Quick Start Guide

Generate your first complete API documentation with a step-by-step tutorial