API Types

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
Mobile Routes
Site Routes

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

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

// 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
HTTP Endpoint
Programmatic

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

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"

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:

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,
    ],
],

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']);
});

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'],
]

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

What Are API Types?

Admin API

Mobile API

Site API

Configuration

Configuration Options

How API Types Work

Route Matching

Internal Matching Logic

Filtering by API Type

Generate Specific API Types

Filter Effect on Output

Validation & Error Handling

Invalid API Type

Disabled API Type

Organization in Output

Postman Collection Structure

Insomnia Workspace Structure

OpenAPI Tags

Adding Custom API Types

Best Practices

Common Use Cases

Next Steps

Environments

Routes Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Documentation Index

​What Are API Types?

Admin API

Mobile API

Site API

​Configuration

​Configuration Options

​How API Types Work

​Route Matching

​Internal Matching Logic

​Filtering by API Type

​Generate Specific API Types

​Filter Effect on Output

​Validation & Error Handling

​Invalid API Type

​Disabled API Type

​Organization in Output

​Postman Collection Structure

​Insomnia Workspace Structure

​OpenAPI Tags

​Adding Custom API Types

​Best Practices

​Common Use Cases

​Next Steps

Environments

Routes Configuration

Build docs developers (and LLMs) love

What Are API Types?

Configuration

Configuration Options

How API Types Work

Route Matching

Internal Matching Logic

Filtering by API Type

Generate Specific API Types

Filter Effect on Output

Validation & Error Handling

Invalid API Type

Disabled API Type

Organization in Output

Postman Collection Structure

Insomnia Workspace Structure

OpenAPI Tags

Adding Custom API Types

Best Practices

Common Use Cases

Next Steps