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.

Admin API

Backend management endpoints for administrators

Mobile API

Optimized endpoints for mobile applications

Site API

Public-facing endpoints for web clients

Configuration

API types are configured in config/openapi.php:

'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

prefix

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.

'prefix' => 'admin',  // Matches: /admin/*, but not /admin itself

The prefix must match exactly. Use lowercase and avoid trailing slashes.

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.

'file' => 'routes/api.admin.php',

description

Type: string (optional)

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

'description' => 'Admin API - Backend management endpoints requiring elevated privileges',

folder_name

Type: string (optional)

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

'folder_name' => 'API Admin',  // Appears as folder in Postman

icon

Type: string (optional)

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

'icon' => '🔐',  // Shows in generated docs

middleware

Type: array (optional)

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

'middleware' => ['api', 'auth:sanctum', 'admin'],

enabled

Type: boolean (default: true)

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

'enabled' => env('ENABLE_MOBILE_API', true),

Setting enabled: false prevents any routes with this prefix from appearing in documentation.

How API Types Work

Route Matching

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

Admin Routes

// routes/api.admin.php
Route::prefix('admin')->group(function () {
    Route::get('users', [UserController::class, 'index']);
    // URI: /admin/users
    // API Type: admin ✓
});

Mobile Routes

// routes/api.mobile.php
Route::prefix('mobile')->group(function () {
    Route::get('feed', [FeedController::class, 'index']);
    // URI: /mobile/feed
    // API Type: mobile ✓
});

Site Routes

// routes/api.site.php
Route::prefix('site')->group(function () {
    Route::get('products', [ProductController::class, 'index']);
    // URI: /site/products
    // API Type: site ✓
});

Internal Matching Logic

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

CLI

Generate documentation for specific API types only:

# 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

HTTP Endpoint

Filter via query parameters:

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

Programmatic

Use the facade or service class:

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

Filter Effect on Output

When API types are filtered, the generated title reflects the selection:

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

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

Error: Unknown or disabled API types: invalid

Available API types:
  - admin
  - site
  - mobile

Disabled API Type

// config/openapi.php
'api_types' => [
    'mobile' => [
        'enabled' => false,  // Disabled
    ],
],

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:

{
  "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:

1. Define API Type

   Add your configuration to config/openapi.php:

   '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,
       ],
   ],
   
2. Create Routes

   Define routes with the matching prefix:

   // 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']);
   });
   
3. Generate Documentation

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

   The new API type is automatically recognized and documented.

Best Practices

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

Logical Separation

• Separate by consumer: admin, mobile, web
• Or by domain: payments, users, products
• Avoid mixing both strategies in the same application

Security Configuration

• Document middleware requirements in the config
• Use different authentication schemes per API type
• Consider rate limiting per API type

Common Use Cases

Multi-Platform Applications

Separate APIs for web, mobile, and admin:

'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

Versioned APIs

Use API types for versioning:

'api_types' => [
    'v1' => ['prefix' => 'v1', 'folder_name' => 'API v1'],
    'v2' => ['prefix' => 'v2', 'folder_name' => 'API v2'],
]

Generate separate documentation for each version to avoid confusion.

Microservice Integration

Document internal vs external APIs:

'api_types' => [
    'public' => ['prefix' => 'api', 'folder_name' => 'Public API'],
    'internal' => ['prefix' => 'internal', 'folder_name' => 'Internal Services'],
]

Next Steps

Environments

Configure deployment environments for your API types

Routes Configuration

Advanced route filtering and exclusion patterns