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

# API Types

> Organize your API documentation by consumer type

## What Are API Types?

API types allow you to segment your API documentation based on different consumers or use cases. Each API type represents a distinct set of routes with its own prefix, making it easy to generate targeted documentation.

<CardGroup cols={3}>
  <Card title="Admin API" icon="lock">
    Backend management endpoints for administrators
  </Card>

  <Card title="Mobile API" icon="mobile">
    Optimized endpoints for mobile applications
  </Card>

  <Card title="Site API" icon="globe">
    Public-facing endpoints for web clients
  </Card>
</CardGroup>

## Configuration

API types are configured in `config/openapi.php`:

```php theme={null}
'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'file' => 'api.admin.php',
        'description' => 'Admin API - Backend management endpoints',
        'folder_name' => 'API Admin',
        'icon' => '🔐',
        'middleware' => ['api'],
        'enabled' => true,
    ],
    'site' => [
        'prefix' => 'site',
        'file' => 'api.frontend.php',
        'description' => 'Frontend Public API - Public facing endpoints',
        'folder_name' => 'API Frontend',
        'icon' => '🌐',
        'middleware' => ['api'],
        'enabled' => true,
    ],
    'mobile' => [
        'prefix' => 'mobile',
        'file' => 'api.mobile.php',
        'description' => 'Mobile API - Mobile application endpoints',
        'folder_name' => 'API Mobile',
        'icon' => '📱',
        'middleware' => ['api'],
        'enabled' => true,
    ],
],
```

### Configuration Options

<Accordion title="prefix" icon="tag">
  **Type:** `string` (required)

  The route prefix that identifies this API type. Routes starting with this prefix will be included in this API type's documentation.

  ```php theme={null}
  'prefix' => 'admin',  // Matches: /admin/*, but not /admin itself
  ```

  <Note>
    The prefix must match exactly. Use lowercase and avoid trailing slashes.
  </Note>
</Accordion>

<Accordion title="file" icon="file">
  **Type:** `string` (optional)

  Reference to the route file where this API type's routes are defined. This is informational and helps developers understand where routes are located.

  ```php theme={null}
  'file' => 'routes/api.admin.php',
  ```
</Accordion>

<Accordion title="description" icon="comment">
  **Type:** `string` (optional)

  A detailed description of what this API type is for. Used in generated documentation.

  ```php theme={null}
  'description' => 'Admin API - Backend management endpoints requiring elevated privileges',
  ```
</Accordion>

<Accordion title="folder_name" icon="folder">
  **Type:** `string` (optional)

  The display name used in Postman collections and Insomnia workspaces. This is how the API type will appear in folder structures.

  ```php theme={null}
  'folder_name' => 'API Admin',  // Appears as folder in Postman
  ```
</Accordion>

<Accordion title="icon" icon="icons">
  **Type:** `string` (optional)

  An emoji or icon identifier used for visual distinction in documentation.

  ```php theme={null}
  'icon' => '🔐',  // Shows in generated docs
  ```
</Accordion>

<Accordion title="middleware" icon="shield">
  **Type:** `array` (optional)

  Middleware groups applied to this API type's routes. Used for documenting security requirements.

  ```php theme={null}
  'middleware' => ['api', 'auth:sanctum', 'admin'],
  ```
</Accordion>

<Accordion title="enabled" icon="toggle-on">
  **Type:** `boolean` (default: `true`)

  Whether this API type is active. Disabled API types are completely ignored during generation.

  ```php theme={null}
  'enabled' => env('ENABLE_MOBILE_API', true),
  ```

  <Info>
    Setting `enabled: false` prevents any routes with this prefix from appearing in documentation.
  </Info>
</Accordion>

## How API Types Work

### Route Matching

Routes are assigned to API types based on their URI prefix:

<Tabs>
  <Tab title="Admin Routes">
    ```php theme={null}
    // routes/api.admin.php
    Route::prefix('admin')->group(function () {
        Route::get('users', [UserController::class, 'index']);
        // URI: /admin/users
        // API Type: admin ✓
    });
    ```
  </Tab>

  <Tab title="Mobile Routes">
    ```php theme={null}
    // routes/api.mobile.php
    Route::prefix('mobile')->group(function () {
        Route::get('feed', [FeedController::class, 'index']);
        // URI: /mobile/feed
        // API Type: mobile ✓
    });
    ```
  </Tab>

  <Tab title="Site Routes">
    ```php theme={null}
    // routes/api.site.php
    Route::prefix('site')->group(function () {
        Route::get('products', [ProductController::class, 'index']);
        // URI: /site/products
        // API Type: site ✓
    });
    ```
  </Tab>
</Tabs>

### Internal Matching Logic

```php theme={null}
// From OpenApiServices.php
protected function isApiRoute(string $uri): bool
{
    $apiPrefixes = array_column($this->getEnabledApiTypes(), 'prefix');

    foreach ($apiPrefixes as $prefix) {
        if (Str::startsWith($uri, $prefix . '/') || $uri === $prefix) {
            return true;
        }
    }
    
    return false;
}
```

## Filtering by API Type

### Generate Specific API Types

<Tabs>
  <Tab title="CLI">
    Generate documentation for specific API types only:

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

    # All formats for specific types
    php artisan openapi:generate --all --api-type=admin --api-type=mobile
    ```
  </Tab>

  <Tab title="HTTP Endpoint">
    Filter via query parameters:

    ```bash theme={null}
    # Single API type
    curl "http://localhost:8000/documentation/openapi.json?api_type=admin"

    # Multiple API types (comma-separated)
    curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"

    # Postman collection for mobile only
    curl "http://localhost:8000/documentation/postman?api_type=mobile"
    ```
  </Tab>

  <Tab title="Programmatic">
    Use the facade or service class:

    ```php theme={null}
    use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

    // Generate for specific API types
    $spec = OpenApiGenerator::generate(
        useCache: false,
        apiTypes: ['admin', 'mobile']
    );

    // The spec will only include routes from /admin/* and /mobile/*
    ```
  </Tab>
</Tabs>

### Filter Effect on Output

<Info>
  When API types are filtered, the generated title reflects the selection:
</Info>

```php theme={null}
// No filter
"title": "My Application"

// With filter: ['admin']
"title": "My Application (API Admin)"

// With filter: ['admin', 'mobile']
"title": "My Application (API Admin, API Mobile)"
```

## Validation & Error Handling

The package validates API types before generation:

### Invalid API Type

```bash theme={null}
php artisan openapi:generate --api-type=invalid
```

```
Error: Unknown or disabled API types: invalid

Available API types:
  - admin
  - site
  - mobile
```

### Disabled API Type

```php theme={null}
// config/openapi.php
'api_types' => [
    'mobile' => [
        'enabled' => false,  // Disabled
    ],
],
```

```bash theme={null}
php artisan openapi:generate --api-type=mobile
```

```
Error: Unknown or disabled API types: mobile
```

## Organization in Output

### Postman Collection Structure

```
My Application
├── 📁 API Admin
│   ├── 📁 Security
│   │   ├── GET List Users
│   │   └── POST Create User
│   └── 📁 Settings
│       └── GET Get Settings
└── 📁 API Mobile
    ├── 📁 Feed
    │   └── GET Get Feed
    └── 📁 Profile
        └── GET Get Profile
```

### Insomnia Workspace Structure

```
My Application Workspace
├── 📁 API Admin
│   └── (Same as Postman)
└── 📁 API Mobile
    └── (Same as Postman)
```

### OpenAPI Tags

Each API type is reflected in OpenAPI tags:

```json theme={null}
{
  "tags": [
    {
      "name": "Users",
      "description": "Users management endpoints",
      "x-api-type": "admin",
      "x-display-name": "API Admin"
    },
    {
      "name": "Feed",
      "description": "Feed management endpoints",
      "x-api-type": "mobile",
      "x-display-name": "API Mobile"
    }
  ]
}
```

## Adding Custom API Types

You can easily add your own API types:

<Steps>
  <Step title="Define API Type">
    Add your configuration to `config/openapi.php`:

    ```php theme={null}
    'api_types' => [
        // ... existing types
        
        'partner' => [
            'prefix' => 'partner',
            'description' => 'Partner API - Third-party integration endpoints',
            'folder_name' => 'API Partner',
            'icon' => '🤝',
            'middleware' => ['api', 'partner.auth'],
            'enabled' => true,
        ],
    ],
    ```
  </Step>

  <Step title="Create Routes">
    Define routes with the matching prefix:

    ```php theme={null}
    // routes/api.partner.php
    Route::prefix('partner')->middleware(['api', 'partner.auth'])->group(function () {
        Route::get('webhooks', [WebhookController::class, 'index']);
        Route::post('webhooks', [WebhookController::class, 'store']);
    });
    ```
  </Step>

  <Step title="Generate Documentation">
    ```bash theme={null}
    php artisan openapi:generate --api-type=partner
    ```

    The new API type is automatically recognized and documented.
  </Step>
</Steps>

## Best Practices

<Note>
  **Consistent Naming**

  * Use lowercase for prefixes: `admin`, not `Admin`
  * Use descriptive folder\_name values: `API Admin` instead of just `Admin`
  * Keep icons consistent across similar API types
</Note>

<Note>
  **Logical Separation**

  * Separate by **consumer**: `admin`, `mobile`, `web`
  * Or by **domain**: `payments`, `users`, `products`
  * Avoid mixing both strategies in the same application
</Note>

<Note>
  **Security Configuration**

  * Document middleware requirements in the config
  * Use different authentication schemes per API type
  * Consider rate limiting per API type
</Note>

## Common Use Cases

<Accordion title="Multi-Platform Applications">
  Separate APIs for web, mobile, and admin:

  ```php theme={null}
  'api_types' => [
      'web' => ['prefix' => 'web', 'folder_name' => 'Web App'],
      'mobile' => ['prefix' => 'mobile', 'folder_name' => 'Mobile App'],
      'admin' => ['prefix' => 'admin', 'folder_name' => 'Admin Dashboard'],
  ]
  ```

  **Benefits:**

  * Mobile team only sees mobile endpoints
  * Admin team has separate documentation
  * Different rate limits per platform
</Accordion>

<Accordion title="Versioned APIs">
  Use API types for versioning:

  ```php theme={null}
  'api_types' => [
      'v1' => ['prefix' => 'v1', 'folder_name' => 'API v1'],
      'v2' => ['prefix' => 'v2', 'folder_name' => 'API v2'],
  ]
  ```

  <Info>
    Generate separate documentation for each version to avoid confusion.
  </Info>
</Accordion>

<Accordion title="Microservice Integration">
  Document internal vs external APIs:

  ```php theme={null}
  'api_types' => [
      'public' => ['prefix' => 'api', 'folder_name' => 'Public API'],
      'internal' => ['prefix' => 'internal', 'folder_name' => 'Internal Services'],
  ]
  ```
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Environments" icon="globe" href="/concepts/environments">
    Configure deployment environments for your API types
  </Card>

  <Card title="Routes Configuration" icon="route" href="/configuration/routes">
    Advanced route filtering and exclusion patterns
  </Card>
</CardGroup>