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, it is marked with ⚙️ in the option's description.

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. ⚙️ `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. ⚙️ `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. ⚙️ `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. ⚙️ `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
`mode`	`classic`	swagger-php mode: `classic`, `hybrid` or `spec`, see Modes. ⚙️ `L5_SWAGGER_SCAN_MODE`
`open_api_spec_version`	`3.0.0`	OpenAPI version of the generated document, for example `3.1.0`. ⚙️ `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],
],

Modes

Added in L5-Swagger 11.3.0. scanOptions.mode picks how swagger-php builds the document. swagger-php's modes guide describes each in full.

classic is the default. Classic attributes and docblock annotations go through swagger-php's processors, as in earlier versions of L5-Swagger.
hybrid reads classic attributes, docblock annotations and spec attributes, and builds the document through swagger-php's augmenters.
spec reads spec attributes only.

swagger-php 7 deprecates classic mode, and swagger-php 8 removes it. Hybrid is the way to try a project on the new pipeline without changing its attributes.

The scan options apply differently per mode:

Option	`hybrid`	`spec`
`processors`	Run on their own, without swagger-php's processors around them. `after` is ignored.	Not used.
`default_processors_configuration`	`generator.*` keys configure the generator, all other keys the augmenters.	All keys configure the augmenters.
`analyser`, `generator_factory`	Used for the classic attributes and docblock annotations; spec attributes are read without them.	Not used.
`analysis`	An error.	An error.

The augmenters take their own keys, for example ['pathFilter' => ['tags' => ['/pets/']]]. php vendor/bin/openapi --mode hybrid -D lists them. An unknown key is reported as a warning, which Laravel turns into an exception.

With builder_factory, the factory sets the mode on its builder. Setting scanOptions.mode to anything but classic next to it is an error.

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. ⚙️ `L5_SWAGGER_GENERATE_ALWAYS`
`generate_yaml_copy`	`false`	Also write a YAML copy of the JSON file. ⚙️ `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. ⚙️ `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. ⚙️ `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. ⚙️ `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`. ⚙️ `L5_SWAGGER_UI_DOC_EXPANSION`
`display.filter`	`true`	Show a box to filter the operations by tag. ⚙️ `L5_SWAGGER_UI_FILTERS`
`authorization.persist_authorization`	`false`	Keep the authorization data when the browser is closed or the page reloads. ⚙️ `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.

openapi-introspector ships a factory that builds the documentation from the application's routes, see Related Projects.

Navigation Menu

Repository navigation

Configuration

Configuration

Structure

Documentation options

Shared options

Routes

Paths

Scan options

Modes

Security definitions

Generation

Swagger UI

Options read from one place only

Custom generator or builder

`generator_factory`

`builder_factory`

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally