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.

This guide covers the fundamental ways to generate OpenAPI, Postman, and Insomnia documentation from your Laravel routes.

​
Generate via Artisan

The simplest way to generate documentation is using the openapi:generate Artisan command: 
php artisan openapi:generate
The --all flag generates OpenAPI + Postman + Insomnia for all API types in a single command.

​
Output Location

By default, files are written to storage/app/public/openapi/. The generator creates these files:
  • openapi.json - OpenAPI 3.0.3 specification
  • postman-all.json - Postman collection (when using --with-postman or --all)
  • insomnia-all.json - Insomnia workspace (when using --with-insomnia or --all)
  • postman-env-*.json - Environment files for artisan, local, and production

​
Common CLI Options

1

Generate specific formats

Use format flags to control which documentation types are generated:
# OpenAPI + Postman only
php artisan openapi:generate --with-postman

# OpenAPI + Insomnia only
php artisan openapi:generate --with-insomnia

# All formats
php artisan openapi:generate --all
2

Filter by API type

Generate documentation for specific API segments:
# Single API type
php artisan openapi:generate --api-type=admin

# Multiple API types
php artisan openapi:generate --api-type=admin --api-type=mobile

# Combine with all formats
php artisan openapi:generate --all --api-type=admin --api-type=mobile
API types must be defined and enabled in config/openapi.php under the api_types key.
3

Choose output format

Specify JSON or YAML for the OpenAPI specification:
# JSON (default)
php artisan openapi:generate --format=json

# YAML
php artisan openapi:generate --format=yaml

​
Expected CLI Output

When you run the command successfully, you’ll see output like this: 
🚀 Generating OpenAPI Specification...

📦 Generating for all API types
📋 Inspecting routes...
✅ Found 47 unique paths
💾 Writing OpenAPI specification...
✅ OpenAPI specification generated!
📄 File: /var/www/storage/app/public/openapi/openapi.json
📦 Format: json
📢 Paths: 47

✨ Generation complete!

​
Generate via HTTP Routes

When openapi.routes.enabled is set to true in your configuration, the package automatically registers HTTP endpoints for on-demand documentation generation.

​
Available Endpoints

# JSON format
curl http://localhost:8000/documentation/openapi.json

# YAML format
curl http://localhost:8000/documentation/openapi.yaml
Returns an OpenAPI 3.0.3 specification document.

​
Query Parameters

Filter documentation using query parameters: 
curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"
HTTP endpoints generate documentation in real-time. For large route sets, this may cause timeouts. Consider generating via CLI and serving static files instead.

​
Configuring HTTP Routes

Configure the HTTP endpoints in config/openapi.php: 
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',  // Accessible at /documentation/*
    'middleware' => [],  // Add auth or throttling as needed
],
Leave middleware empty for public documentation, or add ['auth:sanctum'] to protect endpoints.

​
Generate Programmatically

You can generate documentation from your own code using the OpenApiGenerator service: 
use Ronu\OpenApiGenerator\OpenApiGenerator;

$generator = app(OpenApiGenerator::class);

// Generate OpenAPI specification
$openapi = $generator->generateOpenApi();

// Generate Postman collection
$postman = $generator->generatePostman();

// Generate Insomnia workspace
$insomnia = $generator->generateInsomnia();

​
Filtering Programmatically

Apply filters before generation: 
use Ronu\OpenApiGenerator\Services\OpenApiServices;

$service = app(OpenApiServices::class);

// Set API type filter
$service->setApiTypeFilter(['admin', 'mobile']);

// Generate with cache disabled
$spec = $service->generate(
    useCache: false,
    apiTypes: ['admin'],
    environment: 'production',
    generationType: 'openapi'
);
  • Custom build pipelines: Generate docs during deployment
  • On-demand generation: Create documentation when certain events occur
  • Multi-tenant apps: Generate per-tenant documentation with different configurations
  • Testing: Verify documentation structure in automated tests

​
Validating Output

After generation, validate your OpenAPI specification:
1

Open in Swagger Editor

Visit editor.swagger.io and import your openapi.json or openapi.yaml file.
2

Import to Postman

  1. Open Postman
  2. Click File > Import
  3. Upload the generated postman-all.json
  4. Import each postman-env-*.json environment file
  5. Select an environment from the dropdown
3

Import to Insomnia

  1. Open Insomnia
  2. Click Import/Export > Import Data > From File
  3. Select the generated insomnia-all.json
  4. Environments are automatically included

​
Route Counting

The generator reports unique paths, not individual HTTP methods. For example: 
✅ Found 47 unique paths
This means 47 distinct URL patterns were found. A single path like /api/users/{id} may have multiple methods (GET, PUT, DELETE), but counts as one path.
If you see ⚠️ No routes found matching the specified filters, check your API type configuration and ensure routes exist with the expected prefixes.

​
Next Steps

Advanced Usage

Explore templates, caching, custom output paths, and programmatic filtering.

Common Scenarios

Real-world examples including multi-API generation and CI/CD workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us