Skip to main content

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.

This guide will walk you through generating your first OpenAPI specification, Postman collection, and Insomnia workspace from your Laravel application.

​
Prerequisites

Before you begin, ensure you have:
  • Laravel 10.x, 11.x, or 12.x installed
  • PHP 8.1 or higher
  • Composer 2.x
If you haven’t installed the package yet, follow the Installation Guide first.

​
Step 1: Install the Package

1

Install via Composer

composer require ronu/laravel-openapi-generator
The package auto-registers via Laravel’s service provider discovery.
2

Publish Configuration (Recommended)

php artisan vendor:publish --tag=openapi-config
This creates config/openapi.php where you can customize your API documentation settings.
3

Verify Installation

Check that the command is available:
php artisan openapi:generate --help

​
Step 2: Generate Your First Spec

Generate an OpenAPI 3.0.3 JSON specification:
php artisan openapi:generate
Output: storage/app/public/openapi/openapi.json
The default output path is storage/app/public/openapi/. You can change this in config/openapi.php under output_path.

​
Step 3: Configure API Types

Most Laravel applications have multiple API surfaces (admin panel, mobile API, public site). Configure these in config/openapi.php:
config/openapi.php
return [
    'api_types' => [
        'admin' => [
            'prefix' => 'admin',
            'folder_name' => 'API Admin',
            'enabled' => true,
        ],
        'mobile' => [
            'prefix' => 'mobile',
            'folder_name' => 'API Mobile',
            'enabled' => true,
        ],
        'site' => [
            'prefix' => 'site',
            'folder_name' => 'API Frontend',
            'enabled' => true,
        ],
    ],
];
Then generate docs for specific API types: 
php artisan openapi:generate --api-type=admin --api-type=mobile

​
Step 4: Access via HTTP (Optional)

Enable HTTP routes in config/openapi.php: 
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => [],
],
Now you can fetch documentation via HTTP: 
curl http://localhost:8000/documentation/openapi.json

​
Filter by API Type

Add query parameters to filter by API type: 
curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"

​
Complete Example: User Management API

Let’s document a complete user management endpoint.

​
1. Create the Route

routes/api.php
Route::prefix('admin')->group(function () {
    Route::apiResource('users', UserController::class);
});

​
2. Create FormRequest Validation

app/Http/Requests/StoreUserRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:8',
            'role' => 'required|in:admin,user',
        ];
    }
}

​
3. Controller

app/Http/Controllers/UserController.php
namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Requests\StoreUserRequest;
use Illuminate\Http\JsonResponse;

class UserController extends Controller
{
    public function store(StoreUserRequest $request): JsonResponse
    {
        $user = User::create($request->validated());
        
        return response()->json([
            'data' => $user,
            'message' => 'User created successfully',
        ], 201);
    }
}

​
4. Generate Documentation

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

​
5. Generated OpenAPI Schema

The package automatically generates:
Generated openapi.json (excerpt)
{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "Store User",
        "operationId": "storeUser",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "password", "role"],
                "properties": {
                  "name": { "type": "string", "maxLength": 255 },
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "minLength": 8 },
                  "role": { "type": "string", "enum": ["admin", "user"] }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully"
          }
        }
      }
    }
  }
}
The package automatically extracts validation rules from FormRequest classes and converts them to OpenAPI schemas!

​
Import Into Tools

​
Postman

  1. Open Postman
  2. Click Import in the top left
  3. Select Upload Files
  4. Import postman-all.json (or postman-admin.json)
  5. Import environment files (postman-env-*.json)
  6. Select environment from the dropdown

​
Insomnia

  1. Open Insomnia
  2. Click Application → Import/Export → Import Data → From File
  3. Select insomnia-all.json
  4. The workspace includes:
    • All requests organized by API type
    • Pre-configured environments (artisan, local, production)
    • Automated tests
    • Minimal API spec tab

​
Swagger UI

  1. Visit Swagger Editor
  2. Click File → Import file
  3. Select openapi.json or openapi.yaml

​
Troubleshooting

Problem: Running php artisan openapi:generate shows “No routes found”Solution:
  • Check exclude_routes in config/openapi.php - you might be excluding too many routes
  • Verify your routes are registered in routes/api.php
  • Run php artisan route:list to see all available routes
Problem: Error “Unknown or disabled API types: xyz”Solution:
  • Check config/openapi.php → api_types
  • Ensure the API type exists and enabled is true
  • Clear config cache: php artisan config:clear
Problem: ${{projectName}} still appears in generated docsSolution:
  • Clear config cache: php artisan config:clear
  • Set values explicitly in config/openapi.php instead of using env()
  • Restart Laravel if using php artisan serve

​
Next Steps

Core Concepts

Learn about API types, environments, and how the package works

Configuration

Explore all configuration options and customization

Usage Guides

Advanced generation techniques and workflows

API Reference

Complete API documentation and command reference

Build docs developers (and LLMs) love

Get started for freeTalk to us