Public API

Overview

The Laravel OpenAPI Generator provides a clean programmatic API for generating OpenAPI specifications, Postman collections, and Insomnia workspaces. You can use either the facade or inject the service directly.

Facade

The package registers a facade for convenient access:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

Facade Accessor

The facade resolves to the Ronu\OpenApiGenerator\OpenApiGenerator service class. Location: src/Facades/OpenApiGenerator.php:10

protected static function getFacadeAccessor(): string
{
    return OpenApiGeneratorService::class;
}

Service Class: OpenApiGenerator

The main service class provides four public methods for generating specifications. Location: src/OpenApiGenerator.php

generate()

Generate a specification in any supported format. Signature:

public function generate(
    bool $useCache = true,
    ?array $apiTypes = null,
    ?string $environment = null,
    string $format = 'openapi'
): array

Parameters:

useCache

bool

default:"true"

Enable or disable cache for generation. When true, results are cached based on the cache configuration.

apiTypes

array|null

default:"null"

Filter by specific API types. Pass an array of type keys (e.g., ['api', 'mobile']). When null, all enabled API types are included.

environment

string|null

default:"null"

Environment name to apply (e.g., 'artisan', 'local', 'production'). When null, uses the default environment from configuration.

format

string

default:"'openapi'"

Output format: 'openapi', 'postman', or 'insomnia'.

Returns: array - The generated specification structure. Example:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

// Generate OpenAPI spec for all API types
$spec = OpenApiGenerator::generate();

// Generate for specific API types with custom environment
$spec = OpenApiGenerator::generate(
    useCache: false,
    apiTypes: ['api', 'mobile'],
    environment: 'production',
    format: 'openapi'
);

generateOpenApi()

Convenience method for generating OpenAPI 3.0.3 specifications. Signature:

public function generateOpenApi(
    bool $useCache = true,
    ?array $apiTypes = null,
    ?string $environment = null
): array

Parameters:

useCache

bool

default:"true"

Enable or disable cache for generation.

apiTypes

array|null

default:"null"

Filter by specific API types.

environment

string|null

default:"null"

Environment name to apply.

Returns: array - OpenAPI 3.0.3 specification. Implementation: This method internally calls generate() with format = 'openapi'. Location: src/OpenApiGenerator.php:22-28 Example:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

// Generate OpenAPI spec
$openapi = OpenApiGenerator::generateOpenApi();

// With filtering
$adminApi = OpenApiGenerator::generateOpenApi(
    apiTypes: ['admin'],
    environment: 'production'
);

generatePostman()

Generate a Postman Collection (v2.1 format). Signature:

public function generatePostman(
    bool $useCache = true,
    ?array $apiTypes = null,
    ?string $environment = null
): array

Parameters:

useCache

bool

default:"true"

Enable or disable cache for generation.

apiTypes

array|null

default:"null"

Filter by specific API types.

environment

string|null

default:"null"

Environment name to apply for base URL and variables.

Returns: array - Postman Collection JSON structure. Implementation: This method internally calls generate() with format = 'postman'. Location: src/OpenApiGenerator.php:30-36 Example:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

// Generate Postman collection
$collection = OpenApiGenerator::generatePostman();

// For specific API with environment
$collection = OpenApiGenerator::generatePostman(
    apiTypes: ['mobile'],
    environment: 'artisan'
);

// Export to file
file_put_contents(
    'postman-collection.json',
    json_encode($collection, JSON_PRETTY_PRINT)
);

generateInsomnia()

Generate an Insomnia Workspace (v4 format). Signature:

public function generateInsomnia(
    bool $useCache = true,
    ?array $apiTypes = null,
    ?string $environment = null
): array

Parameters:

useCache

bool

default:"true"

Enable or disable cache for generation.

apiTypes

array|null

default:"null"

Filter by specific API types.

environment

string|null

default:"null"

Environment name to apply for base URL and variables.

Returns: array - Insomnia Workspace JSON structure. Implementation: This method internally calls generate() with format = 'insomnia'. Location: src/OpenApiGenerator.php:38-44 Example:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

// Generate Insomnia workspace
$workspace = OpenApiGenerator::generateInsomnia();

// For admin API
$workspace = OpenApiGenerator::generateInsomnia(
    apiTypes: ['admin'],
    environment: 'local'
);

// Export to file
file_put_contents(
    'insomnia-workspace.json',
    json_encode($workspace, JSON_PRETTY_PRINT)
);

Dependency Injection

You can also inject the service directly into your controllers or services:

use Ronu\OpenApiGenerator\OpenApiGenerator;

class DocumentationController extends Controller
{
    public function __construct(
        private readonly OpenApiGenerator $generator
    ) {}

    public function export()
    {
        $spec = $this->generator->generateOpenApi(
            apiTypes: ['api'],
            environment: 'production'
        );

        return response()->json($spec);
    }
}

Service Provider

The package is auto-discovered via Laravel’s package discovery. Provider: Ronu\OpenApiGenerator\Providers\OpenApiGeneratorServiceProvider Responsibilities:

Registers OpenApiServices and OpenApiGenerator as singletons
Publishes configuration files
Registers Artisan commands
Registers HTTP routes (if enabled)

Configuration Publishing:

php artisan vendor:publish --tag=openapi-config

HTTP Controller (Optional)

If HTTP routes are enabled (openapi.routes.enabled = true), the package provides a controller for web access. Controller: Ronu\OpenApiGenerator\Controllers\OpenApiController Available HTTP Endpoints:

Route	Method	Description
`/documentation/openapi.{format}`	GET	Generate OpenAPI spec (JSON/YAML)
`/documentation/postman`	GET	Generate Postman collection
`/documentation/insomnia`	GET	Generate Insomnia workspace
`/documentation/environments/{format?}`	GET	Get all environments

Query Parameters:

api_type - Comma-separated list of API types
environment - Environment name

Example HTTP Usage:

# Get OpenAPI spec for mobile API
curl "http://localhost:8000/documentation/openapi.json?api_type=mobile"

# Get Postman collection for admin API in production
curl "http://localhost:8000/documentation/postman?api_type=admin&environment=production"

# Get all environments (Postman format)
curl "http://localhost:8000/documentation/environments/postman"

Return Value Structure

OpenAPI Format

Returns an OpenAPI 3.0.3 compliant specification:

openapi

string

OpenAPI version (3.0.3)

info

object

API metadata (title, version, description, contact, license)

servers

array

Array of server objects with URLs and descriptions

paths

object

All API endpoints with operations (GET, POST, etc.)

Postman Format

Returns a Postman Collection v2.1 structure with:

Collection metadata
Folders grouped by module
Pre-request scripts for token management
Tests for response validation
Variable references

Insomnia Format

Returns an Insomnia v4 workspace with:

Workspace metadata
Request groups
Multiple environments (base + artisan + local + production)
Request chaining via response variables
Automated tests

Error Handling

All methods may throw the following exceptions:

See the Exceptions page for detailed error handling documentation.

Common Exceptions:

InvalidArgumentException - Invalid API type or environment name
Exception - General generation errors (invalid configuration, missing templates)

Example with Error Handling:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

try {
    $spec = OpenApiGenerator::generate(
        apiTypes: ['invalid-type']
    );
} catch (\InvalidArgumentException $e) {
    // Handle invalid API type
    logger()->error('Invalid API type', ['error' => $e->getMessage()]);
} catch (\Exception $e) {
    // Handle other errors
    logger()->error('Generation failed', ['error' => $e->getMessage()]);
}

Cache Management

The service respects the cache configuration in config/openapi.php:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
    'key_prefix' => 'openapi_spec_',
],

Clearing Cache Programmatically: The OpenApiServices class provides a cache clearing method:

use Ronu\OpenApiGenerator\Services\OpenApiServices;

$service = app(OpenApiServices::class);
$service->clearCache();

Clearing Cache via CLI:

# Clear all Laravel cache (includes OpenAPI cache)
php artisan cache:clear

# Generate fresh spec without cache
php artisan openapi:generate --no-cache

Artisan Commands

CLI command reference

Configuration

Configure API types and environments

Exceptions

Error handling guide

HTTP Routes

Configure web endpoints

Reference

Overview

Facade

Facade Accessor

Service Class: OpenApiGenerator

generate()

generateOpenApi()

generatePostman()

generateInsomnia()

Dependency Injection

Service Provider

HTTP Controller (Optional)

Return Value Structure

OpenAPI Format

Postman Format

Insomnia Format

Error Handling

Cache Management

Artisan Commands

Configuration

Exceptions

HTTP Routes

Build docs developers (and LLMs) love

Reference

Documentation Index

​Overview

​Facade

​Facade Accessor

​Service Class: OpenApiGenerator

​generate()

​generateOpenApi()

​generatePostman()

​generateInsomnia()

​Dependency Injection

​Service Provider

​HTTP Controller (Optional)

​Return Value Structure

​OpenAPI Format

​Postman Format

​Insomnia Format

​Error Handling

​Cache Management

​Related Documentation

Artisan Commands

Configuration

Exceptions

HTTP Routes

Build docs developers (and LLMs) love

Overview

Facade

Facade Accessor

Service Class: OpenApiGenerator

generate()

generateOpenApi()

generatePostman()

generateInsomnia()

Dependency Injection

Service Provider

HTTP Controller (Optional)

Return Value Structure

OpenAPI Format

Postman Format

Insomnia Format

Error Handling

Cache Management

Related Documentation