Skip to main content

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.

​
Requirements

Before installing, ensure your environment meets these requirements:
ComponentVersion
PHP8.1+
Laravel10.x, 11.x, or 12.x
Composer2.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: 
<?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' => 'support@example.com',
    ],
],

​
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="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, 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

Build docs developers (and LLMs) love

Get started for freeTalk to us