Artisan Commands - Laravel OpenAPI Generator

Overview

The openapi:generate command is the primary CLI interface for generating OpenAPI specifications, Postman collections, and Insomnia workspaces from your Laravel routes. Command Class: Ronu\OpenApiGenerator\Commands\GenerateOpenApiSpec
Location: src/Commands/GenerateOpenApiSpec.php

Command Signature

php artisan openapi:generate [options]

Full Signature:

php artisan openapi:generate
    {--format=json : Output format (json or yaml)}
    {--output= : Output file path}
    {--no-cache : Disable cache}
    {--api-type=* : Filter by API type (api, site, mobile, admin)}
    {--all : Generate all formats for all channels (OpenAPI + Postman + Insomnia)}
    {--with-postman : Generate Postman collection}
    {--with-insomnia : Generate Insomnia workspace}
    {--environment=artisan : Environment to use (artisan, local, production)}

Location: src/Commands/GenerateOpenApiSpec.php:40-48

Options Reference

—format

Specify the output format for the OpenAPI specification.

string

default:"json"

Output format for OpenAPI specification.Allowed values: json, yaml, ymlDefault: json

Examples:

# Generate JSON format (default)
php artisan openapi:generate

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

Validation: The command validates the format and returns an error for invalid values:

# Invalid format
php artisan openapi:generate --format=xml
# Error: Invalid format. Supported formats: json, yaml

Location: src/Commands/GenerateOpenApiSpec.php:91-94

—output

Override the default output file path.

string

default:"null"

Custom output file path. When not specified, uses the configured output_path from config.Example: /path/to/custom/openapi.json

Default Behavior: When --output is not provided, the command generates files in the directory specified by config('openapi.output_path') (default: storage/app/public/openapi). File Naming Convention:

OpenAPI: openapi-{apiType}.json or openapi-all.json
Postman: postman-{apiType}.json or postman-all.json
Insomnia: insomnia-{apiType}.json or insomnia-all.json

Examples:

# Use default output path
php artisan openapi:generate
# Output: storage/app/public/openapi/openapi-all.json

# Custom output path
php artisan openapi:generate --output=/var/www/docs/api-spec.json
# Output: /var/www/docs/api-spec.json

# Custom path with API type filter
php artisan openapi:generate --api-type=mobile --output=./mobile-api.json
# Output: ./mobile-api.json

—no-cache

Disable caching for this generation run.

flag

default:"false"

When present, bypasses the cache and forces fresh generation. Useful during development or when routes have changed.

Default Behavior: By default, the command uses caching if enabled in config('openapi.cache.enabled'). The cache key includes the API types, environment, and format. Cache Configuration:

// config/openapi.php
'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
    'key_prefix' => 'openapi_spec_',
],

Examples:

# Use cache (default)
php artisan openapi:generate

# Force fresh generation
php artisan openapi:generate --no-cache

# Force fresh generation for specific API type
php artisan openapi:generate --api-type=admin --no-cache

Location: src/Commands/GenerateOpenApiSpec.php:82

—api-type

Filter routes by API type. Can be specified multiple times for multiple API types.

string[]

default:"[]"

Filter by one or more API types. Can be repeated for multiple types.Common values: api, site, mobile, adminMultiple values: Repeat the option or use array syntax

API Types: API types are configured in config/openapi.php under the api_types key. Each type has:

prefix - Route prefix (e.g., api, mobile)
folder_name - Display name
enabled - Whether the type is active

Examples:

# Generate for all API types (default)
php artisan openapi:generate

# Generate only for 'api' type
php artisan openapi:generate --api-type=api

# Generate for multiple API types
php artisan openapi:generate --api-type=api --api-type=mobile

# Alternative multiple types syntax
php artisan openapi:generate --api-type=admin --api-type=mobile

Output File Naming:

# Single API type
php artisan openapi:generate --api-type=mobile
# Output: storage/app/public/openapi/openapi-mobile.json

# Multiple API types
php artisan openapi:generate --api-type=api --api-type=mobile
# Output: storage/app/public/openapi/openapi-api-mobile.json

Validation: The command validates API types against enabled types in configuration:

# Invalid API type
php artisan openapi:generate --api-type=invalid
# Error: Unknown or disabled API types: invalid. Available types: api, mobile, admin

Location: src/Commands/GenerateOpenApiSpec.php:83, 109-118

—all

Generate all artifact formats (OpenAPI + Postman + Insomnia) for all API types.

flag

default:"false"

When present, generates OpenAPI specification, Postman collection, and Insomnia workspace for ALL enabled API types.Equivalent to: --with-postman --with-insomnia with no --api-type filter

Behavior: When --all is used:

Ignores --api-type filters (generates for all enabled types)
Automatically enables Postman and Insomnia generation
Creates files named with -all suffix

Output Files:

openapi-all.json (or .yaml)
postman-all.json
insomnia-all.json
postman-env-artisan.json
postman-env-local.json
postman-env-production.json

Examples:

# Generate everything
php artisan openapi:generate --all

# Generate everything in YAML format
php artisan openapi:generate --all --format=yaml

# Generate everything without cache
php artisan openapi:generate --all --no-cache

Console Output:

🚀 Generating OpenAPI Specification...

📦 Generating ALL artifacts for ALL API types

📋 Inspecting routes...
✅ Found 45 unique paths
💾 Writing OpenAPI specification...
✅ OpenAPI specification generated!
📄 File: storage/app/public/openapi/openapi-all.json
📦 Format: json
📢 Paths: 45

📮 Generating Postman collection...
✅ Postman collection generated!
📄 File: storage/app/public/openapi/postman-all.json
📋 Generating Postman environments...
  ├─ artisan: storage/app/public/openapi/postman-env-artisan.json
  ├─ local: storage/app/public/openapi/postman-env-local.json
  └─ production: storage/app/public/openapi/postman-env-production.json

🛏️  Generating Insomnia workspace...
✅ Insomnia workspace generated!
📄 File: storage/app/public/openapi/insomnia-all.json
  ├─ Includes 3 environments (base + artisan + local + production)
  ├─ Minimal API Spec tab
  └─ Automated tests included

✨ Generation complete! (--all mode)

Location: src/Commands/GenerateOpenApiSpec.php:84, 104-106, 176-221

—with-postman

Generate Postman collection in addition to OpenAPI specification.

flag

default:"false"

When present, generates a Postman Collection v2.1 along with the OpenAPI spec.Also generates environment files for artisan, local, and production.

Output Files:

Postman collection: postman-{apiType}.json
Environment files:
- postman-env-artisan.json
- postman-env-local.json
- postman-env-production.json

Examples:

# Generate OpenAPI + Postman
php artisan openapi:generate --with-postman

# For specific API type
php artisan openapi:generate --api-type=admin --with-postman

# Multiple API types with Postman
php artisan openapi:generate --api-type=api --api-type=mobile --with-postman

Postman Collection Features:

Pre-request scripts for token extraction
Request folders organized by module
Environment variable placeholders ({{base_url}}, {{token}})
Response validation tests
Variable tracking (e.g., last_user_id for chaining requests)

Import Instructions:

📥 Import instructions:

  Postman Collection:
    1. Import postman-admin.json
    2. Import each postman-env-*.json file
    3. Select environment from dropdown

Location: src/Commands/GenerateOpenApiSpec.php:85-86, 145-152, 247-278

—with-insomnia

Generate Insomnia workspace in addition to OpenAPI specification.

flag

default:"false"

When present, generates an Insomnia Workspace v4 along with the OpenAPI spec.Includes multiple environments (base + artisan + local + production) embedded in the workspace.

Output Files:

Insomnia workspace: insomnia-{apiType}.json

Examples:

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

# For specific API type
php artisan openapi:generate --api-type=mobile --with-insomnia

# Both Postman and Insomnia
php artisan openapi:generate --with-postman --with-insomnia

Insomnia Workspace Features:

Multiple environments included (no separate files needed)
Request chaining with response variable extraction
Automated test suites
Minimal API Spec tab (OpenAPI viewer)
Request folders organized by module

Import Instructions:

📥 Import instructions:

  Insomnia Workspace:
    1. Import insomnia-mobile.json
    2. Environments are already included
    3. Check Spec, Collection, and Test tabs

Location: src/Commands/GenerateOpenApiSpec.php:86-87, 149-152, 283-305

—environment

Select the environment configuration for base URLs and variables.

string

default:"artisan"

Environment name to use for server URLs and variable values.Common values: artisan, local, productionDefault: artisan

Environment Configuration: Environments are defined in config/openapi.php under the environments key:

'environments' => [
    'artisan' => [
        'name' => 'Artisan Server',
        'base_url' => 'http://127.0.0.1:8000',
        'parent' => 'base',
    ],
    'local' => [
        'name' => 'Local Server',
        'base_url' => 'http://localhost/myapp/public',
        'parent' => 'base',
    ],
    'production' => [
        'name' => 'Production Server',
        'base_url' => 'https://api.example.com',
        'parent' => 'base',
    ],
],

Effect on Generation: The environment determines:

The servers array in OpenAPI spec
Base URL variables in Postman/Insomnia
Environment-specific variable values

Examples:

# Use artisan environment (default)
php artisan openapi:generate

# Use local environment
php artisan openapi:generate --environment=local

# Production environment with API type
php artisan openapi:generate --api-type=api --environment=production

# All formats with production environment
php artisan openapi:generate --all --environment=production

Validation: The command validates environment names and falls back to artisan for unknown values:

# Unknown environment
php artisan openapi:generate --environment=staging
# Warning: Unknown environment 'staging', using 'artisan' as default

Location: src/Commands/GenerateOpenApiSpec.php:87, 96-101

Usage Examples

Basic Usage

# Generate OpenAPI spec with defaults
php artisan openapi:generate

Output:

🚀 Generating OpenAPI Specification...

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

✨ Generation complete!

Generate for Specific API Type

# Admin API only
php artisan openapi:generate --api-type=admin

Output:

🚀 Generating OpenAPI Specification...

🔍 Filtering API types: admin
📋 Inspecting routes...
✅ Found 12 unique paths
💾 Writing OpenAPI specification...
✅ OpenAPI specification generated!
📄 File: storage/app/public/openapi/openapi-admin.json
📦 Format: json
📢 Paths: 12

✨ Generation complete!

Generate Multiple API Types with Postman

php artisan openapi:generate --api-type=api --api-type=mobile --with-postman

Output:

🚀 Generating OpenAPI Specification...

🔍 Filtering API types: api, mobile
📋 Inspecting routes...
✅ Found 33 unique paths
💾 Writing OpenAPI specification...
✅ OpenAPI specification generated!
📄 File: storage/app/public/openapi/openapi-api-mobile.json
📦 Format: json
📢 Paths: 33

📮 Generating Postman collection...
✅ Postman collection generated!
📄 File: storage/app/public/openapi/postman-api-mobile.json
📋 Generating Postman environments...
  ├─ artisan: storage/app/public/openapi/postman-env-artisan.json
  ├─ local: storage/app/public/openapi/postman-env-local.json
  └─ production: storage/app/public/openapi/postman-env-production.json

✨ Generation complete!

Generate Everything (All Formats)

php artisan openapi:generate --all

Output: Generates OpenAPI + Postman + Insomnia for all enabled API types.

Production Export with Custom Path

php artisan openapi:generate \
  --format=yaml \
  --api-type=api \
  --environment=production \
  --output=/var/www/public/api-docs.yaml \
  --no-cache

Development Workflow

# During development, regenerate without cache
php artisan openapi:generate --no-cache --with-postman --with-insomnia

# Test specific module
php artisan openapi:generate --api-type=admin --no-cache

# Export for client
php artisan openapi:generate --api-type=api --environment=production --format=yaml

Output Files

Default Output Directory

Files are saved to the path specified in config/openapi.php:

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

Default location: storage/app/public/openapi/

File Naming Convention

Scenario	File Name
All API types (OpenAPI)	`openapi-all.json`
Single API type (OpenAPI)	`openapi-{type}.json`
Multiple API types (OpenAPI)	`openapi-{type1}-{type2}.json`
Postman collection	`postman-{type}.json`
Insomnia workspace	`insomnia-{type}.json`
Postman environment	`postman-env-{env}.json`
YAML format	`.yaml` instead of `.json`

Location: src/Commands/GenerateOpenApiSpec.php:136-139 and src/Services/OpenApiServices.php:1493-1505

Error Handling

Invalid Format

php artisan openapi:generate --format=xml

Output:

❌ Invalid format. Supported formats: json, yaml

Exit Code: 1 (FAILURE)

Invalid API Type

php artisan openapi:generate --api-type=invalid

Output:

❌ Failed to generate specification
Unknown or disabled API types: invalid. Available types: api, mobile, admin

Exit Code: 1 (FAILURE)

No Routes Found

php artisan openapi:generate --api-type=site

Output:

🚀 Generating OpenAPI Specification...

🔍 Filtering API types: site
📋 Inspecting routes...
✅ Found 0 unique paths
⚠️  No routes found matching the specified filters

Exit Code: 0 (SUCCESS) - Not treated as error

Verbose Error Output

For detailed error information, use the -v flag:

php artisan openapi:generate --api-type=admin -v

Location: src/Commands/GenerateOpenApiSpec.php:161-170

Exit Codes

Code	Constant	Meaning
`0`	`self::SUCCESS`	Generation successful
`1`	`self::FAILURE`	Generation failed (invalid input, exception)

Location: src/Commands/GenerateOpenApiSpec.php:160, 169, 220

Integration with CI/CD

GitHub Actions

name: Generate API Documentation

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - name: Install Dependencies
        run: composer install --no-dev --optimize-autoloader
      - name: Generate OpenAPI Spec
        run: |
          php artisan openapi:generate \
            --format=yaml \
            --environment=production \
            --output=./public/openapi.yaml \
            --no-cache
      - name: Deploy to Docs
        # Upload to S3, GitHub Pages, etc.

GitLab CI

generate-docs:
  stage: build
  script:
    - php artisan openapi:generate --all --no-cache
  artifacts:
    paths:
      - storage/app/public/openapi/
    expire_in: 1 week

Public API

Programmatic generation API

Configuration

Configure API types and environments

Postman Export

Working with Postman collections

Insomnia Export

Working with Insomnia workspaces

​Overview

​Command Signature

​Options Reference

​—format

​—output

​—no-cache

​—api-type

​—all

​—with-postman

​—with-insomnia

​—environment

​Usage Examples

​Basic Usage

​Generate for Specific API Type

​Generate Multiple API Types with Postman

​Generate Everything (All Formats)

​Production Export with Custom Path

​Development Workflow

​Output Files

​Default Output Directory

​File Naming Convention

​Error Handling

​Invalid Format

​Invalid API Type

​No Routes Found

​Verbose Error Output

​Exit Codes

​Integration with CI/CD

​GitHub Actions

​GitLab CI

​Related Documentation

Public API

Configuration

Postman Export

Insomnia Export

Overview

Command Signature

Options Reference

—format

—output

—no-cache

—api-type

—all

—with-postman

—with-insomnia

—environment

Usage Examples

Basic Usage

Generate for Specific API Type

Generate Multiple API Types with Postman

Generate Everything (All Formats)

Production Export with Custom Path

Development Workflow

Output Files

Default Output Directory

File Naming Convention

Error Handling

Invalid Format

Invalid API Type

No Routes Found

Verbose Error Output

Exit Codes

Integration with CI/CD

GitHub Actions

GitLab CI

Related Documentation