Publishing Assets

The Laravel OpenAPI Generator service provider publishes two groups of assets: configuration files and template files. This guide explains what gets published, how to customize them, and best practices.

Configuration Files

Publish all configuration files with a single command:

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

Published Files

This command publishes four configuration files to your config/ directory:

config/openapi.php

Main configuration file containing:

OpenAPI metadata (title, version, contact, license)
Server definitions for different environments
Security scheme definitions (Bearer, API Key, etc.)
Hierarchical environments for Postman/Insomnia
API type configurations (admin, site, mobile)
Module scanning paths and exclusions
Cache settings
Output path configuration
Model and request class paths
Route filtering and exclusions
Middleware to security mapping
Default response examples
HTTP route configuration

File location: config/openapi.php

config/openapi-docs.php

CRUD and entity documentation configuration containing:

CRUD template definitions (summary, description, response templates)
Entity metadata (singular/plural names, model classes, descriptions)
Custom endpoint documentation
Auto-detection settings for fields and relationships
Field description overrides
Field example overrides

File location: config/openapi-docs.php

config/openapi-templates.php

Template system configuration containing:

Template system enable/disable toggle
Template directory paths (generic and custom)
Generic template mappings for actions
Query builder documentation settings
Auto-detection configuration for models
Rendering options (debug, validation, caching)
Example generation settings
Performance limits and caching

File location: config/openapi-templates.php

config/openapi-tests.php

Test generation configuration containing:

Test template definitions for CRUD actions
Test script snippets for Postman
Test script snippets for Insomnia
Custom test overrides for specific endpoints
Verbose logging settings

File location: config/openapi-tests.php

Customizing Configuration

After publishing, you can customize any configuration values:

// Customize API metadata
'info' => [
    'title' => 'My Custom API',
    'description' => 'This is my amazing API',
    'version' => '2.0.0',
],

// Add custom security schemes
'security' => [
    'BearerAuth' => [
        'type' => 'http',
        'scheme' => 'bearer',
        'bearerFormat' => 'JWT',
    ],
    'OAuth2' => [
        'type' => 'oauth2',
        'flows' => [
            'authorizationCode' => [
                'authorizationUrl' => 'https://example.com/oauth/authorize',
                'tokenUrl' => 'https://example.com/oauth/token',
                'scopes' => [
                    'read' => 'Read access',
                    'write' => 'Write access',
                ],
            ],
        ],
    ],
],

// Customize API types
'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'file' => 'api.admin.php',
        'folder_name' => 'Admin API',
        'icon' => '🔒',
        'enabled' => true,
    ],
    'v2' => [
        'prefix' => 'v2',
        'file' => 'api.v2.php',
        'folder_name' => 'API v2',
        'icon' => '✨',
        'enabled' => true,
    ],
],

Configuration changes take effect immediately. If caching is enabled, you may need to clear the cache:

php artisan cache:clear

Template Files

Publish template files separately:

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

Published Template Structure

Templates are published to resources/openapi/templates/ with the following structure:

resources/openapi/templates/
├── generic/
│   ├── index.json
│   ├── show.json
│   ├── store.json
│   ├── update.json
│   ├── destroy.json
│   └── ...
└── custom/
    └── (your custom endpoint templates)

Template Types

Generic Templates

Location: resources/openapi/templates/generic/Generic templates define documentation structure for common CRUD operations:

index.json: List/paginated collection endpoints
show.json: Single resource retrieval
store.json: Resource creation
update.json: Resource updates
destroy.json: Resource deletion

These templates use placeholders that are automatically replaced with model-specific data during generation.Example: generic/show.json

{
  "summary": "Get {{singular}}",
  "description": "Retrieve a single {{singular}} by ID",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {"type": "integer"}
    }
  ],
  "responses": {
    "200": {
      "description": "Successful operation",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/{{model}}"
          }
        }
      }
    }
  }
}

Custom Templates

Location: resources/openapi/templates/custom/Custom templates allow you to define documentation for non-CRUD endpoints or override generic templates for specific resources.Example: custom/users_login.json

{
  "summary": "User Login",
  "description": "Authenticate a user and return an access token",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": ["email", "password"],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "example": "user@example.com"
            },
            "password": {
              "type": "string",
              "format": "password",
              "example": "secret123"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Login successful",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "token": {"type": "string"},
              "user": {"$ref": "#/components/schemas/User"}
            }
          }
        }
      }
    },
    "401": {
      "description": "Invalid credentials"
    }
  }
}

Template Placeholders

Templates support automatic placeholder replacement:

Placeholder	Replaced With	Example
`{{model}}`	Model class name	`User`
`{{singular}}`	Singular entity name	`user`
`{{plural}}`	Plural entity name	`users`
`{{table}}`	Database table name	`users`
`{{primaryKey}}`	Primary key field	`id`
`{{fields}}`	Model fields	Auto-generated from model
`{{relationships}}`	Model relationships	Auto-generated from model

Placeholders are automatically extracted from your models using reflection and database schema inspection.

Publishing Workflow

Initial Setup

When setting up a new project:

# 1. Install the package
composer require ronu/laravel-openapi-generator

# 2. Publish configuration files
php artisan vendor:publish --tag=openapi-config

# 3. (Optional) Publish templates if you need customization
php artisan vendor:publish --tag=openapi-templates

# 4. Customize configuration
vim config/openapi.php

# 5. Generate documentation
php artisan openapi:generate

Updating Published Assets

When updating the package to a new version:

Publishing again will overwrite your customized files. Back up your changes first.

# Backup existing config
cp config/openapi.php config/openapi.php.backup

# Re-publish
php artisan vendor:publish --tag=openapi-config --force

# Compare and merge changes
diff config/openapi.php.backup config/openapi.php

Better approach: Use version control and selectively merge new options:

# See what changed in the package
git diff vendor/ronu/laravel-openapi-generator/config/

# Manually add new config options to your published files

File Locations Reference

Configuration Files

File	Location	Purpose
`openapi.php`	`config/openapi.php`	Main configuration
`openapi-docs.php`	`config/openapi-docs.php`	CRUD and entity docs
`openapi-templates.php`	`config/openapi-templates.php`	Template system
`openapi-tests.php`	`config/openapi-tests.php`	Test generation

Template Files

Directory	Location	Purpose
Generic templates	`resources/openapi/templates/generic/`	CRUD templates
Custom templates	`resources/openapi/templates/custom/`	Custom endpoint templates

Generated Output

Type	Location	Description
OpenAPI specs	`storage/app/public/openapi/openapi/`	JSON/YAML specifications
Postman collections	`storage/app/public/openapi/postman/`	Postman collection files
Insomnia collections	`storage/app/public/openapi/insomnia/`	Insomnia workspace files

Output location can be customized via the openapi.output_path configuration option.

Advanced Customization

Custom Security Schemes

Add OAuth2, OpenID Connect, or custom authentication:

config/openapi.php

'security' => [
    'OAuth2' => [
        'type' => 'oauth2',
        'flows' => [
            'authorizationCode' => [
                'authorizationUrl' => 'https://auth.example.com/authorize',
                'tokenUrl' => 'https://auth.example.com/token',
                'refreshUrl' => 'https://auth.example.com/refresh',
                'scopes' => [
                    'read:users' => 'Read user data',
                    'write:users' => 'Modify user data',
                    'admin' => 'Administrative access',
                ],
            ],
        ],
    ],
],

'middleware_security_map' => [
    'auth:sanctum' => ['BearerAuth'],
    'oauth' => ['OAuth2'],
    'scopes:admin' => ['OAuth2'],
],

Multiple API Versions

Document multiple API versions simultaneously:

config/openapi.php

'api_types' => [
    'v1' => [
        'prefix' => 'v1',
        'file' => 'api.v1.php',
        'description' => 'API Version 1 (Deprecated)',
        'folder_name' => 'API v1',
        'icon' => '📦',
        'middleware' => ['api', 'api.v1'],
        'enabled' => true,
    ],
    'v2' => [
        'prefix' => 'v2',
        'file' => 'api.v2.php',
        'description' => 'API Version 2 (Current)',
        'folder_name' => 'API v2',
        'icon' => '✨',
        'middleware' => ['api'],
        'enabled' => true,
    ],
],

Custom Response Schemas

Add custom response schemas for your API:

config/openapi.php

'response_examples' => [
    '200' => [
        'description' => 'Successful operation',
        'content' => [
            'application/json' => [
                'schema' => [
                    'type' => 'object',
                    'properties' => [
                        'success' => ['type' => 'boolean', 'example' => true],
                        'data' => ['type' => 'object'],
                        'meta' => [
                            'type' => 'object',
                            'properties' => [
                                'timestamp' => ['type' => 'string', 'format' => 'date-time'],
                                'request_id' => ['type' => 'string'],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
],

Environment-Specific Servers

Define servers for different deployment environments:

config/openapi.php

'servers' => [
    [
        'url' => 'http://localhost:8000',
        'description' => 'Local Development',
    ],
    [
        'url' => 'https://staging-api.mycompany.com',
        'description' => 'Staging Environment',
    ],
    [
        'url' => 'https://api.mycompany.com',
        'description' => 'Production Environment',
    ],
],

Best Practices

Version Control

Commit published files to version control:

git add config/openapi*.php
git add resources/openapi/templates/
git commit -m "Add OpenAPI configuration"

This ensures all team members use the same configuration.

Environment-Specific Overrides

Use .env for environment-specific values:

config/openapi.php

'info' => [
    'title' => env('APP_NAME', 'Laravel API'),
    'version' => env('API_VERSION', '1.0.0'),
],

Then set different values per environment:

.env.production

APP_NAME="Production API"
API_VERSION=2.0.0

Selective Publishing

Publish only what you need:

# Publish only configuration (most common)
php artisan vendor:publish --tag=openapi-config

# Publish templates only if you need customization
php artisan vendor:publish --tag=openapi-templates

You don’t need to publish templates unless you’re customizing them.

Documentation

Document your customizations:Add comments to your config files explaining custom settings:

config/openapi.php

// Custom security scheme for our OAuth2 provider
'security' => [
    'OAuth2' => [
        // Configuration for Auth0 integration
        'type' => 'oauth2',
        // ...
    ],
],

Template Inheritance

Use custom templates sparingly:Only create custom templates when generic templates don’t fit. This reduces maintenance burden when the package is updated.Good:

custom/
└── users_login.json  (truly custom endpoint)

Avoid:

custom/
├── users_index.json  (could use generic/index.json)
├── users_show.json   (could use generic/show.json)
└── users_store.json  (could use generic/store.json)

Troubleshooting

Config files not updating

Problem: Changes to config files don’t take effect.Solution: Clear configuration cache:

php artisan config:clear
php artisan cache:clear

Templates not found

Problem: Generator can’t find custom templates.Solution: Verify template paths in config/openapi-templates.php:

'paths' => [
    'generic' => resource_path('openapi/templates/generic'),
    'custom' => resource_path('openapi/templates/custom'),
],

Ensure directories exist:

mkdir -p resources/openapi/templates/{generic,custom}

Publishing overwrites customizations

Problem: Re-publishing overwrites your changes.Solution: Use version control and selective merging:

# Before re-publishing
git commit -am "Backup current config"

# Re-publish with force
php artisan vendor:publish --tag=openapi-config --force

# Review and merge
git diff HEAD~1

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Configuration Files

Published Files

Customizing Configuration

Template Files

Published Template Structure

Template Types

Template Placeholders

Publishing Workflow

Initial Setup

Updating Published Assets

File Locations Reference

Configuration Files

Template Files

Generated Output

Advanced Customization

Custom Security Schemes

Multiple API Versions

Custom Response Schemas

Environment-Specific Servers

Best Practices

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Documentation Index

​Configuration Files

​Published Files

​Customizing Configuration

​Template Files

​Published Template Structure

​Template Types

​Template Placeholders

​Publishing Workflow

​Initial Setup

​Updating Published Assets

​File Locations Reference

​Configuration Files

​Template Files

​Generated Output

​Advanced Customization

​Custom Security Schemes

​Multiple API Versions

​Custom Response Schemas

​Environment-Specific Servers

​Best Practices

​Troubleshooting

Build docs developers (and LLMs) love

Configuration Files

Published Files

Customizing Configuration

Template Files

Published Template Structure

Template Types

Template Placeholders

Publishing Workflow

Initial Setup

Updating Published Assets

File Locations Reference

Configuration Files

Template Files

Generated Output

Advanced Customization

Custom Security Schemes

Multiple API Versions

Custom Response Schemas

Environment-Specific Servers

Best Practices

Troubleshooting