l5-swagger Documentation

L5 Swagger is a Laravel wrapper for swagger-php and swagger-ui. It is designed to make generating and serving OpenAPI or Swagger specifications easy within a Laravel application.

Note: This package does not define the Swagger specification itself; it provides the integration layer. For instructions on how to write the actual Swagger specification using annotations, refer to the swagger-php documentation.

To customize the package behavior or the UI, you can publish the configuration file and the view files to your application.

Use the config tag to publish the configuration file to config/l5-swagger.php:

php artisan vendor:publish --tag=config

Use the views tag to publish the views to the path defined in your configuration (defaulting to the path specified in l5-swagger.defaults.paths.views):

php artisan vendor:publish --tag=views

L5-Swagger allows you to define security schemes (like Bearer tokens or API keys) and apply security requirements to your OpenAPI documentation. This is handled via the SecurityDefinitions class, which injects settings from your L5-Swagger configuration into the generated JSON documentation.

To use this, ensure your l5-swagger configuration file contains the appropriate security_schemes and security keys. The generate() method will then read your existing JSON documentation, append these security definitions, and overwrite the file with the updated content.

If the documentation file cannot be found at the expected path, the system will return a 404 error. Verify that the file exists in the location defined by your configuration keys:

• paths.docs
• paths.docs_json (if format is json)
• paths.docs_yaml (if format is yaml)

Common error message format: Unable to locate documentation file at: "{path}"

If the documentation fails to generate, the system may return a 404 error with a specific message. Ensure that the directory specified in your configuration is writable.

Common error message format: Unable to generate documentation file to: "{path}". Please make sure directory is writable. Error: {error_message}

The L5Swagger\Generator class is responsible for scanning your project's annotations and producing OpenAPI documentation files (JSON and optionally YAML). To trigger the generation process, call the generateDocs() method. This method handles directory preparation, constant definition, file scanning, server population, and file saving.

$generator = new \L5Swagger\Generator(
    $paths, 
    $constants, 
    $yamlCopyRequired, 
    $security, 
    $scanOptions
);
$generator->generateDocs();

The GeneratorFactory::make() method creates and returns a new Generator instance configured for a specific documentation set. It uses the documentation identifier (the name/key defined in your configuration) to resolve paths, scan options, constants, and security definitions.

When calling make(string $documentation), the factory resolves the following configuration keys from your documentation settings:

• paths: The directories to scan for annotations.
• scanOptions: Options for the scanner (optional).
• constants: Constants to be used during generation (optional).
• generate_yaml_copy: Boolean indicating if a YAML copy should be generated (defaults to false).
• securityDefinitions: Configuration for securitySchemes and security settings.

Use the documentationConfig() method to retrieve the merged configuration for a specific documentation set.

• If you pass null, it retrieves the configuration for the documentation specified in l5-swagger.default.
• If you pass a string, it retrieves the configuration for the documentation key specified in l5-swagger.documentations.

The method performs a recursive merge where values from the specific documentation configuration override the values in l5-swagger.defaults.

Throws L5Swagger amespace\ L5SwaggerException if the specified documentation configuration is not found in the l5-swagger.documentations array.