Skip to content

Configuration

DerManoMann edited this page Oct 25, 2026 · 6 revisions

Configuration

L5-Swagger reads its settings from config/l5-swagger.php. To get a copy of that file in your project, publish it:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Many options can also be set through an environment variable. Where one exists, the option's description names it.

Structure

The file has three top-level keys:

  • default: the name of the documentation that is used when none is given, for example by php artisan l5-swagger:generate without arguments.
  • documentations: one entry per documentation. Each entry has its own title, routes and paths.
  • defaults: settings shared by all documentations.

For each documentation, L5-Swagger merges its entry over defaults:

  • Arrays with string keys are merged key by key, so a documentation only needs to set the keys it changes.
  • Lists, such as paths.annotations or scanOptions.exclude, are replaced as a whole.
  • Any other value set in the documentation replaces the default.

A second documentation, with its own routes and source directory:

'documentations' => [
    'default' => [
        // ...
    ],
    'admin' => [
        'api' => [
            'title' => 'Admin API',
        ],
        'routes' => [
            'api' => 'api/admin/documentation',
            'docs' => 'docs/admin',
        ],
        'paths' => [
            'docs_json' => 'admin-api-docs.json',
            'docs_yaml' => 'admin-api-docs.yaml',
            'annotations' => [
                base_path('app/Admin'),
            ],
        ],
    ],
],

Each documentation needs its own routes.api and routes.docs. Routes with the same path replace each other, so two documentations that share the default docs route both serve one of the two files. docs_json and docs_yaml need to differ too, as all documentations write to the same paths.docs directory by default.

Run php artisan l5-swagger:generate admin to generate one documentation, or php artisan l5-swagger:generate --all for all of them.

Documentation options

These are set per entry under documentations.

Option Default Description
api.title L5 Swagger UI Title of the Swagger UI page, and the name of this documentation in the UI's selector.
routes.api api/documentation Path of the Swagger UI page.
paths.use_absolute_path true Whether the UI links its assets and the documentation file with full URLs. Environment variable: L5_SWAGGER_USE_ABSOLUTE_PATH.
paths.swagger_ui_assets_path vendor/swagger-api/swagger-ui/dist/ Directory of the Swagger UI assets, relative to the project root. Environment variable: L5_SWAGGER_UI_ASSETS_PATH.
paths.docs_json api-docs.json File name of the generated JSON file.
paths.docs_yaml api-docs.yaml File name of the YAML copy.
paths.format_to_use_for_docs json Which file the UI loads: json or yaml. yaml also needs generate_yaml_copy, as the YAML file is only written then. Environment variable: L5_FORMAT_TO_USE_FOR_DOCS.
paths.annotations [base_path('app')] Directories that are scanned for attributes.

Shared options

These are set under defaults. Any of them can also be set in a documentation entry to override it there, with the exceptions listed under Options read from one place only.

Routes

Option Default Description
routes.docs docs Path that serves the generated file. The UI's assets are served below it, at docs/asset/{asset}.
routes.oauth2_callback api/oauth2-callback Path of the OAuth2 callback used by the UI.
routes.middleware.api [] Middleware for the UI page.
routes.middleware.docs [] Middleware for the generated file.
routes.middleware.asset [] Middleware for the UI's assets.
routes.middleware.oauth2_callback [] Middleware for the OAuth2 callback.
routes.group_options [] Options for the route group around all of the above, for example a prefix or domain.

The middleware lists are empty by default, so the documentation is public. To restrict access in production, add authentication middleware, for example 'api' => ['auth:sanctum'].

Paths

Option Default Description
paths.docs storage_path('api-docs') Directory the generated files are written to. It is created if it does not exist.
paths.views base_path('resources/views/vendor/l5-swagger') Where vendor:publish copies the views to.
paths.base null If set, added to the document as a server URL. Environment variable: L5_SWAGGER_BASE_PATH.
paths.excludes [] Deprecated, use scanOptions.exclude.

Scan options

These are set under scanOptions, and configure how swagger-php scans the source and builds the document.

Option Default Description
open_api_spec_version 3.0.0 OpenAPI version of the generated document, for example 3.1.0. Environment variable: L5_SWAGGER_OPEN_API_SPEC_VERSION.
pattern *.php File name pattern of the files to scan.
exclude [] Directories to leave out of the scan. If not empty, it replaces paths.excludes.
processors [] Additional processors, see below.
default_processors_configuration [] Configuration for swagger-php's own processors, for example ['operationId.hash' => true]. See swagger-php's processor reference.
analyser null Analyser to use. By default the attributes are read through reflection.
analysis null Analysis object to start from. By default a new one is used.
generator_factory null Class name or instance of a CustomGeneratorInterface, see Custom generator or builder.
builder_factory null Class name or instance of a CustomBuilderInterface, see Custom generator or builder.

Each entry in scanOptions.processors is a processor class name or instance, which is added after swagger-php's BuildPaths. To add it somewhere else, use an array with the processor to follow:

'processors' => [
    \App\SwaggerProcessors\SchemaQueryParameter::class,
    ['class' => \App\SwaggerProcessors\Custom::class, 'after' => \OpenApi\Processors\AugmentSchemas::class],
],

Security definitions

securityDefinitions adds security to the generated file, after the scan:

  • securityDefinitions.securitySchemes: each entry is added to components.securitySchemes, under its key. An entry replaces a scheme of the same name from the attributes.
  • securityDefinitions.security: the document's security requirements. Each non-empty entry replaces the requirement at the same position in the document.

The published config has commented-out examples for an API key, OAuth2, Passport and Sanctum.

Generation

Option Default Description
generate_always false Generate the documentation on every request to the docs route. Useful during development; in production it logs a warning, as it slows down each request. Environment variable: L5_SWAGGER_GENERATE_ALWAYS.
generate_yaml_copy false Also write a YAML copy of the JSON file. Environment variable: L5_SWAGGER_GENERATE_YAML_COPY.
constants ['L5_SWAGGER_CONST_HOST' => ...] PHP constants defined before the scan, so attributes can use them. A constant that is already defined keeps its value. Environment variable: L5_SWAGGER_CONST_HOST.

Swagger UI

Option Default Description
proxy false IP address, or list of addresses, of trusted proxies, for example an AWS load balancer.
additional_config_url null URL of an external Swagger UI configuration, see the configs plugin. It has to start with http:// or https://, any other value is ignored with a warning in the log.
operations_sort null Sort the operations by path (alpha) or by HTTP method (method). By default, they are listed in the order of the document. Environment variable: L5_SWAGGER_OPERATIONS_SORT.
validator_url null Validator URL for the UI. null turns validation off.

The display and authorization settings are set under ui:

Option Default Description
display.dark_mode false Show the UI in dark mode. Environment variable: L5_SWAGGER_UI_DARK_MODE.
display.doc_expansion none What is expanded when the page loads: list (the tags), full (tags and operations) or none. Environment variable: L5_SWAGGER_UI_DOC_EXPANSION.
display.filter true Show a box to filter the operations by tag. Environment variable: L5_SWAGGER_UI_FILTERS.
authorization.persist_authorization false Keep the authorization data when the browser is closed or the page reloads. Environment variable: L5_SWAGGER_UI_PERSIST_AUTHORIZATION.

ui.authorization.oauth2.use_pkce_with_authorization_code_grant, default false, adds PKCE to the OAuth2 authorization code flow. It only applies if a scheme in securityDefinitions.securitySchemes has the type oauth2.

Options read from one place only

Most options can be set in defaults and overridden per documentation. These cannot:

  • ui.* is read from defaults only, so all documentations share one UI configuration. So is the check for an oauth2 scheme that turns on PKCE: it looks at defaults.securityDefinitions.securitySchemes, not at a scheme a documentation adds.
  • paths.use_absolute_path and paths.swagger_ui_assets_path are read from the documentation entry only. Setting them in defaults has no effect.
  • paths.views is read from defaults only, when the views are published.

Custom generator or builder

By default, L5-Swagger creates swagger-php's generator itself and configures it from the scan options. To set it up in code instead, point one of these options at a class of your own. Only one of the two can be set; setting both is an error.

generator_factory

Added in L5-Swagger 11.1.0. The class implements L5Swagger\CustomGeneratorInterface and returns an OpenApi\Generator:

use L5Swagger\CustomGeneratorInterface;
use OpenApi\Generator;

class MyGeneratorFactory implements CustomGeneratorInterface
{
    public function create(): Generator
    {
        return new Generator();
    }
}

L5-Swagger then applies the scan options to the generator it returns: open_api_spec_version, default_processors_configuration, processors and the analyser. The analyser is always replaced, by scanOptions.analyser or by the default one, so an analyser set in the factory is not used. To use a custom analyser, set scanOptions.analyser.

builder_factory

Added in L5-Swagger 11.2.1. The class implements L5Swagger\CustomBuilderInterface and returns an OpenApi\Builder:

use L5Swagger\CustomBuilderInterface;
use OpenApi\Builder;

class MyBuilderFactory implements CustomBuilderInterface
{
    public function create(): Builder
    {
        return new Builder();
    }
}

The factory owns the whole build: the mode, augmenters and anything else the builder supports. L5-Swagger only sets open_api_spec_version, and adds paths.base as a server. The scan options processors, analyser, analysis and default_processors_configuration configure the generator, so they are not used with a builder.

Setting paths.base with a builder needs zircote/swagger-php 6.12 or later.

Clone this wiki locally