Geni Configuration File Reference: config/geni.php

Geni ships with a single configuration file that controls everything from API metadata and route discovery to security schemes, documentation routing, and MCP server behaviour. Before customising any option, publish the default file into your project’s config directory so Laravel loads your local copy instead of the package default.

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

The file is written to config/geni.php. Every key shown in this reference corresponds directly to a key in that file.

Document Information (`info`)

The info block defines the top-level metadata that appears in the OpenAPI info object and in the rendered documentation UI.

'title'            => null, // defaults to config('app.name')
'version'          => '1.0.0',
'description'      => 'REST API documentation generated by Geni.',
'terms_of_service' => 'https://example.com/terms',

'contact' => [
    'name'  => 'API Support',
    'email' => 'support@example.com',
    'url'   => 'https://example.com/support',
],

'license' => [
    'name' => 'MIT',
    'url'  => 'https://opensource.org/licenses/MIT',
],

Key	Type	Description
`title`	`string\|null`	Displayed title for the API. When `null`, falls back to `config('app.name')`.
`version`	`string`	Semantic version string included in the OpenAPI spec and UI header.
`description`	`string`	Short description rendered below the API title.
`terms_of_service`	`string`	URL to your terms of service page.
`contact.name`	`string`	Name of the support contact.
`contact.email`	`string`	Support email address.
`contact.url`	`string`	URL to the support page.
`license.name`	`string`	License name (e.g. `MIT`, `Apache-2.0`).
`license.url`	`string`	URL to the full licence text.

Route Discovery

These options tell Geni which routes to include in the generated specification. By default, Geni discovers every route whose URI starts with the api_path prefix.

// Routes matching this URI prefix are included in documentation:
'api_path' => 'api',

// Optional custom domain where API routes are served:
'api_domain' => null,

// Optional closure returning a filtered array of Route objects:
'routes' => null,

Key	Type	Description
`api_path`	`string`	URI prefix used to filter which routes are documented. Set to `'api/v1'` to document only v1 routes, for example.
`api_domain`	`string\|null`	Restrict discovery to routes served on a specific domain. Leave `null` to match any domain.
`routes`	`Closure\|null`	A closure that receives the full route collection and returns an array of `Route` objects to document. Use this for precise control when prefix or domain matching is not enough.

When routes is set, Geni ignores api_path and api_domain for route filtering. The closure has full access to the route collection, so you can combine path, domain, name, and middleware checks in a single place.

Database Migrations

Geni replays your migration history offline to derive column types for Eloquent model schemas — no live database connection required.

'migration_paths' => [
    database_path('migrations'),
],

Key	Type	Description
`migration_paths`	`array`	List of directories Geni scans for migration files. Add additional paths if your application splits migrations across packages or domains.

Schema Overrides

When Geni cannot infer a column type from your migrations — for example, because a migration uses a raw SQL expression or a database-specific column type — you can supply the correct type manually.

'schema_overrides' => [
    'users.balance'    => 'number',
    'orders.metadata'  => 'object',
],

Each key is a table.column string. The value is any valid JSON Schema primitive type: string, number, integer, boolean, object, or array.

Treat schema_overrides as an escape hatch, not a first resort. If Geni misses a type that it should be able to infer, check geni:analyze output first — there may be a migration pattern you can simplify so that static analysis picks it up automatically.

Security Schemes

Geni inspects route middleware to determine which endpoints require authentication and which OpenAPI security scheme to attach to them.

// Middleware patterns that mark endpoints as requiring authentication:
'middleware_security' => [
    'auth',
    'auth:*',
],

// Default OpenAPI security scheme applied to all matched endpoints:
'security_scheme' => [
    'type'         => 'http',
    'scheme'       => 'bearer',
    'bearerFormat' => 'JWT',
    'description'  => 'Bearer token authentication',
],

// Per-middleware custom security schemes (override the default above):
'middleware_security_schemes' => [
    'auth:sanctum' => [
        'name'   => 'sanctumAuth',
        'scheme' => [
            'type'         => 'http',
            'scheme'       => 'bearer',
            'bearerFormat' => 'JWT',
        ],
    ],
    'auth:api-key' => [
        'name'   => 'apiKeyAuth',
        'scheme' => [
            'type' => 'apiKey',
            'in'   => 'header',
            'name' => 'X-API-Key',
        ],
    ],
],

Key	Type	Description
`middleware_security`	`array`	Middleware names (glob patterns accepted) that indicate a route requires authentication.
`security_scheme`	`array`	The default OpenAPI security scheme object to attach when a matching middleware is found.
`middleware_security_schemes`	`array`	A map of specific middleware names to named security schemes. Entries here take precedence over `security_scheme` for their respective middleware.

The middleware_security_schemes map lets you emit different security requirements for different auth guards. The auth:sanctum entry above produces a sanctumAuth bearer scheme, while auth:api-key produces an apiKeyAuth API key scheme — each appearing in the correct securitySchemes component and referenced from the appropriate endpoint.

Documentation Routing

These options control the URLs where Geni serves the documentation UI and the raw OpenAPI JSON, as well as who can access them.

// URL path for the interactive documentation UI:
'docs_ui_path'     => 'docs/api',

// URL path for the raw OpenAPI JSON specification:
'docs_json_path'   => 'docs/api.json',

// Return 404 in any environment other than 'local' when true:
'restrict_to_local' => true,

// Middleware applied to all documentation routes:
'middleware' => [
    // 'web',
],

Key	Type	Description
`docs_ui_path`	`string`	URI path for the documentation UI.
`docs_json_path`	`string`	URI path for the raw JSON spec endpoint.
`restrict_to_local`	`bool`	When `true`, documentation routes return `404` in any environment other than `local`.
`middleware`	`array`	Laravel middleware applied to the docs routes. Add `'web'` to enable session-based authentication.

restrict_to_local defaults to true. If you want to expose documentation in staging or production, set this to false and protect the routes using the middleware array and/or docs_auth credentials instead.

Documentation Authentication

When you need to gate access to the documentation UI with a login prompt, configure docs_auth. Geni supports both HTTP Basic authentication and a simple HTML form login.

'docs_auth' => [
    // 'form' shows an HTML login page; 'basic' triggers a browser HTTP Basic prompt:
    'mode'     => env('GENI_DOCS_AUTH_MODE', 'basic'),
    'username' => env('GENI_DOCS_USERNAME'),
    'password' => env('GENI_DOCS_PASSWORD'),
],

Key	Type	Description
`mode`	`string`	Authentication prompt style. `'basic'` uses HTTP Basic auth; `'form'` renders an HTML login page.
`username`	`string`	Username checked against the incoming credentials.
`password`	`string`	Password checked against the incoming credentials.

Store your credentials in .env rather than hard-coding them in config/geni.php. The env() defaults shown above mean you can set GENI_DOCS_USERNAME and GENI_DOCS_PASSWORD per environment without touching the config file.

Multi-Version APIs

The apis key lets you define multiple independent API surfaces — each with its own route prefix, title, version string, and any other top-level configuration option — within a single Laravel application.

'apis' => [
    'v1' => [
        'title'    => 'API v1',
        'version'  => '1.0.0',
        'api_path' => 'api/v1',
    ],
    'v2' => [
        'title'    => 'API v2',
        'version'  => '2.0.0',
        'api_path' => 'api/v2',
    ],
],

Each key (v1, v2) becomes the --api name accepted by every geni:* Artisan command. Any top-level configuration option can be overridden inside an API entry — options not specified in the entry fall back to the root-level value.

Use geni:export --api=v1 and geni:export --api=v2 in your CI pipeline to produce separate committed spec files for each version. Use geni:check --api=v1 and geni:check --api=v2 independently to detect drift in either version.

Model Context Protocol

The mcp block configures Geni’s MCP server — the component that exposes your API as callable tools to AI desktop clients. Enable it, define which routes to surface, and configure authentication for outbound HTTP execution requests.

'mcp' => [
    'enabled'         => true,
    'route_path'      => 'docs/api/mcp',
    'tool_naming'     => 'snake',   // 'snake' or 'operation_id'
    'include_tags'    => [],
    'exclude_tags'    => [],
    'exclude_methods' => ['HEAD', 'OPTIONS'],

    'execution' => [
        'base_url'   => env('GENI_MCP_BASE_URL'),
        'timeout'    => 15,
        'verify_ssl' => true,

        'auth' => [
            'default_bearer_token' => env('GENI_MCP_BEARER_TOKEN'),
            'default_api_key'      => env('GENI_MCP_API_KEY'),
            'api_key_header'       => 'X-API-Key',
        ],
    ],
],

Key	Type	Description
`enabled`	`bool`	Enable or disable the MCP server and its route entirely.
`route_path`	`string`	URI path where the MCP manifest endpoint is served.
`tool_naming`	`string`	Tool name generation strategy. `'snake'` derives names from method and path; `'operation_id'` uses the OpenAPI `operationId`.
`include_tags`	`array`	When non-empty, only routes tagged with one of these values are exposed as MCP tools.
`exclude_tags`	`array`	Routes tagged with any of these values are excluded from the MCP tool list.
`exclude_methods`	`array`	HTTP methods to exclude from the tool list. Defaults to `['HEAD', 'OPTIONS']`.
`execution.base_url`	`string\|null`	Base URL prepended to all tool execution HTTP requests. Defaults to `config('app.url')`.
`execution.timeout`	`integer`	Seconds before an outbound tool execution request times out.
`execution.verify_ssl`	`bool`	Whether to verify TLS certificates on outbound execution requests.
`execution.auth.default_bearer_token`	`string\|null`	Bearer token injected into the `Authorization` header of every tool execution request.
`execution.auth.default_api_key`	`string\|null`	API key injected into the configured `api_key_header` of every tool execution request.
`execution.auth.api_key_header`	`string`	Header name used to transmit the `default_api_key`. Defaults to `'X-API-Key'`.

Set GENI_MCP_BEARER_TOKEN or GENI_MCP_API_KEY in your .env file — not directly in config/geni.php — to avoid committing credentials. These values are forwarded by the MCP server when it proxies tool calls to your application on behalf of an AI client.

Getting Started

Core Concepts

Integrations

Annotations

Guides

Reference

Geni Configuration File Reference: config/geni.php

Document Information (`info`)

Route Discovery

Database Migrations

Schema Overrides

Security Schemes

Documentation Routing

Documentation Authentication

Multi-Version APIs

Model Context Protocol

​Document Information (info)

​Route Discovery

​Database Migrations

​Schema Overrides

​Security Schemes

​Documentation Routing

​Documentation Authentication

​Multi-Version APIs

​Model Context Protocol

Document Information (`info`)

Route Discovery

Database Migrations

Schema Overrides

Security Schemes

Documentation Routing

Documentation Authentication

Multi-Version APIs

Model Context Protocol