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

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

<CodeGroup>
  ```bash Default (JSON) theme={null}
  php artisan openapi:generate
  ```

  ```bash YAML Format theme={null}
  php artisan openapi:generate --format=yaml
  ```

  ```bash All Formats theme={null}
  php artisan openapi:generate --all
  ```
</CodeGroup>

<Note>
  The `--all` flag generates OpenAPI + Postman + Insomnia for all API types in a single command.
</Note>

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

<Steps>
  <Step title="Generate specific formats">
    Use format flags to control which documentation types are generated:

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

  <Step title="Filter by API type">
    Generate documentation for specific API segments:

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

    <Note>
      API types must be defined and enabled in `config/openapi.php` under the `api_types` key.
    </Note>
  </Step>

  <Step title="Choose output format">
    Specify JSON or YAML for the OpenAPI specification:

    ```bash theme={null}
    # JSON (default)
    php artisan openapi:generate --format=json

    # YAML
    php artisan openapi:generate --format=yaml
    ```
  </Step>
</Steps>

## Expected CLI Output

When you run the command successfully, you'll see output like this:

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

<Tabs>
  <Tab title="OpenAPI">
    ```bash theme={null}
    # 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.
  </Tab>

  <Tab title="Postman">
    ```bash theme={null}
    curl http://localhost:8000/documentation/postman
    ```

    Returns a Postman Collection v2.1 JSON document with all routes and environments embedded.
  </Tab>

  <Tab title="Insomnia">
    ```bash theme={null}
    curl http://localhost:8000/documentation/insomnia
    ```

    Returns an Insomnia v4 workspace JSON with routes, environments, and API spec tabs.
  </Tab>
</Tabs>

### Query Parameters

Filter documentation using query parameters:

<CodeGroup>
  ```bash Filter by API Type theme={null}
  curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"
  ```

  ```bash Specify Environment theme={null}
  curl "http://localhost:8000/documentation/postman?environment=production"
  ```

  ```bash Combine Filters theme={null}
  curl "http://localhost:8000/documentation/postman?api_type=mobile&environment=production"
  ```
</CodeGroup>

<Warning>
  HTTP endpoints generate documentation in real-time. For large route sets, this may cause timeouts. Consider generating via CLI and serving static files instead.
</Warning>

### Configuring HTTP Routes

Configure the HTTP endpoints in `config/openapi.php`:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',  // Accessible at /documentation/*
    'middleware' => [],  // Add auth or throttling as needed
],
```

<Tip>
  Leave middleware empty for public documentation, or add `['auth:sanctum']` to protect endpoints.
</Tip>

## Generate Programmatically

You can generate documentation from your own code using the `OpenApiGenerator` service:

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

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

<Accordion title="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
</Accordion>

## Validating Output

After generation, validate your OpenAPI specification:

<Steps>
  <Step title="Open in Swagger Editor">
    Visit [editor.swagger.io](https://editor.swagger.io) and import your `openapi.json` or `openapi.yaml` file.
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

## Route Counting

The generator reports unique **paths**, not individual HTTP methods. For example:

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

<Note>
  If you see `⚠️ No routes found matching the specified filters`, check your API type configuration and ensure routes exist with the expected prefixes.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Advanced Usage" icon="wand-magic-sparkles" href="/guides/advanced-usage">
    Explore templates, caching, custom output paths, and programmatic filtering.
  </Card>

  <Card title="Common Scenarios" icon="lightbulb" href="/guides/common-scenarios">
    Real-world examples including multi-API generation and CI/CD workflows.
  </Card>
</CardGroup>