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

# 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

<Note>
  If you haven't installed the package yet, follow the [Installation Guide](/installation) first.
</Note>

## Step 1: Install the Package

<Steps>
  <Step title="Install via Composer">
    ```bash theme={null}
    composer require ronu/laravel-openapi-generator
    ```

    The package auto-registers via Laravel's service provider discovery.
  </Step>

  <Step title="Publish Configuration (Recommended)">
    ```bash theme={null}
    php artisan vendor:publish --tag=openapi-config
    ```

    This creates `config/openapi.php` where you can customize your API documentation settings.
  </Step>

  <Step title="Verify Installation">
    Check that the command is available:

    ```bash theme={null}
    php artisan openapi:generate --help
    ```
  </Step>
</Steps>

## Step 2: Generate Your First Spec

<Tabs>
  <Tab title="OpenAPI JSON">
    Generate an OpenAPI 3.0.3 JSON specification:

    ```bash theme={null}
    php artisan openapi:generate
    ```

    **Output**: `storage/app/public/openapi/openapi.json`

    <Info>
      The default output path is `storage/app/public/openapi/`. You can change this in `config/openapi.php` under `output_path`.
    </Info>
  </Tab>

  <Tab title="OpenAPI YAML">
    Generate a YAML specification instead:

    ```bash theme={null}
    php artisan openapi:generate --format=yaml
    ```

    **Output**: `storage/app/public/openapi/openapi.yaml`
  </Tab>

  <Tab title="All Formats">
    Generate OpenAPI, Postman, and Insomnia all at once:

    ```bash theme={null}
    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)
  </Tab>
</Tabs>

## Step 3: Configure API Types

Most Laravel applications have multiple API surfaces (admin panel, mobile API, public site). Configure these in `config/openapi.php`:

```php config/openapi.php theme={null}
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:

```bash theme={null}
php artisan openapi:generate --api-type=admin --api-type=mobile
```

## Step 4: Access via HTTP (Optional)

Enable HTTP routes in `config/openapi.php`:

```php theme={null}
'routes' => [
    'enabled' => true,
    'prefix' => 'documentation',
    'middleware' => [],
],
```

Now you can fetch documentation via HTTP:

<CodeGroup>
  ```bash OpenAPI JSON theme={null}
  curl http://localhost:8000/documentation/openapi.json
  ```

  ```bash OpenAPI YAML theme={null}
  curl http://localhost:8000/documentation/openapi.yaml
  ```

  ```bash Postman Collection theme={null}
  curl http://localhost:8000/documentation/postman
  ```

  ```bash Insomnia Workspace theme={null}
  curl http://localhost:8000/documentation/insomnia
  ```
</CodeGroup>

### Filter by API Type

Add query parameters to filter by API type:

```bash theme={null}
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

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

### 2. Create FormRequest Validation

```php app/Http/Requests/StoreUserRequest.php theme={null}
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

```php app/Http/Controllers/UserController.php theme={null}
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

```bash theme={null}
php artisan openapi:generate --api-type=admin
```

### 5. Generated OpenAPI Schema

The package automatically generates:

```json Generated openapi.json (excerpt) theme={null}
{
  "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"
          }
        }
      }
    }
  }
}
```

<Tip>
  The package automatically extracts validation rules from FormRequest classes and converts them to OpenAPI schemas!
</Tip>

## 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](https://editor.swagger.io)
2. Click **File** → **Import file**
3. Select `openapi.json` or `openapi.yaml`

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/concepts/overview">
    Learn about API types, environments, and how the package works
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/reference">
    Explore all configuration options and customization
  </Card>

  <Card title="Usage Guides" icon="book" href="/guides/basic-usage">
    Advanced generation techniques and workflows
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/public-api">
    Complete API documentation and command reference
  </Card>
</CardGroup>