Quickstart

Get up and running with Laravel OpenAPI Generator in 5 minutes

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

OpenAPI JSON

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.

OpenAPI YAML

Generate a YAML specification instead:

php artisan openapi:generate --format=yaml

Output: storage/app/public/openapi/openapi.yaml

All Formats

Generate OpenAPI, Postman, and Insomnia all at once:

php artisan openapi:generate --all

Output:

• openapi-all.json
• postman-all.json
• postman-env-artisan.json
• postman-env-local.json
• postman-env-production.json
• insomnia-all.json (includes environments and tests)

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:

OpenAPI JSON

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

No routes found

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

Invalid api_type error

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

Placeholders not updating

Problem: ${{projectName}} still appears in generated docs

Solution:

• 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