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

# Artisan Commands

> Complete reference for the openapi:generate command and all options

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

```bash theme={null}
php artisan openapi:generate [options]
```

**Full Signature:**

```bash theme={null}
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.

<ParamField path="--format" type="string" default="json">
  Output format for OpenAPI specification.

  **Allowed values:** `json`, `yaml`, `yml`

  **Default:** `json`
</ParamField>

**Examples:**

```bash theme={null}
# 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:

```bash theme={null}
# 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.

<ParamField path="--output" type="string" default="null">
  Custom output file path. When not specified, uses the configured `output_path` from config.

  **Example:** `/path/to/custom/openapi.json`
</ParamField>

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

```bash theme={null}
# 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.

<ParamField path="--no-cache" type="flag" default="false">
  When present, bypasses the cache and forces fresh generation. Useful during development or when routes have changed.
</ParamField>

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

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

**Examples:**

```bash theme={null}
# 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.

<ParamField path="--api-type" type="string[]" default="[]">
  Filter by one or more API types. Can be repeated for multiple types.

  **Common values:** `api`, `site`, `mobile`, `admin`

  **Multiple values:** Repeat the option or use array syntax
</ParamField>

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
# 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.

<ParamField path="--all" type="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
</ParamField>

**Behavior:**

When `--all` is used:

1. Ignores `--api-type` filters (generates for all enabled types)
2. Automatically enables Postman and Insomnia generation
3. 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:**

```bash theme={null}
# 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.

<ParamField path="--with-postman" type="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.
</ParamField>

**Output Files:**

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

**Examples:**

```bash theme={null}
# 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.

<ParamField path="--with-insomnia" type="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.
</ParamField>

**Output Files:**

* Insomnia workspace: `insomnia-{apiType}.json`

**Examples:**

```bash theme={null}
# 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.

<ParamField path="--environment" type="string" default="artisan">
  Environment name to use for server URLs and variable values.

  **Common values:** `artisan`, `local`, `production`

  **Default:** `artisan`
</ParamField>

**Environment Configuration:**

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

```php theme={null}
'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:

1. The `servers` array in OpenAPI spec
2. Base URL variables in Postman/Insomnia
3. Environment-specific variable values

**Examples:**

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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)

```bash theme={null}
php artisan openapi:generate --all
```

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

***

### Production Export with Custom Path

```bash theme={null}
php artisan openapi:generate \
  --format=yaml \
  --api-type=api \
  --environment=production \
  --output=/var/www/public/api-docs.yaml \
  --no-cache
```

***

### Development Workflow

```bash theme={null}
# 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`:

```php theme={null}
'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

```bash theme={null}
php artisan openapi:generate --format=xml
```

**Output:**

```
❌ Invalid format. Supported formats: json, yaml
```

**Exit Code:** `1` (FAILURE)

***

### Invalid API Type

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
generate-docs:
  stage: build
  script:
    - php artisan openapi:generate --all --no-cache
  artifacts:
    paths:
      - storage/app/public/openapi/
    expire_in: 1 week
```

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Public API" icon="code" href="/api-reference/public-api">
    Programmatic generation API
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/reference">
    Configure API types and environments
  </Card>

  <Card title="Postman Export" icon="paper-plane" href="/guides/postman-collection">
    Working with Postman collections
  </Card>

  <Card title="Insomnia Export" icon="moon" href="/guides/insomnia-workspace">
    Working with Insomnia workspaces
  </Card>
</CardGroup>