Basic Usage

Learn how to generate OpenAPI specifications using CLI commands and HTTP endpoints

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:

Default (JSON)

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

OpenAPI

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

Postman

curl http://localhost:8000/documentation/postman

Returns a Postman Collection v2.1 JSON document with all routes and environments embedded.

Insomnia

curl http://localhost:8000/documentation/insomnia

Returns an Insomnia v4 workspace JSON with routes, environments, and API spec tabs.

Query Parameters

Filter documentation using query parameters:

Filter by API Type

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'
);

When to use programmatic generation

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