CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

L5-Swagger is a Laravel package that integrates swagger-php and swagger-ui into Laravel. It does NOT implement the OpenAPI spec — it wraps swagger-php for annotation scanning and swagger-ui for the documentation frontend.

Supports multiple independent documentation sets, each with its own routes, paths, and settings via a two-level config: defaults (shared) merged with documentations.{name} (per-doc overrides). ConfigFactory::mergeConfig() recursively merges associative arrays.

Development Commands

# Run all tests
composer run-script phpunit

# Run a single test file
vendor/bin/phpunit tests/Unit/GeneratorTest.php

# Run a single test method
vendor/bin/phpunit --filter testCanGenerateApiJsonFile

# Static analysis (PHPStan level 8)
composer run-script analyse

Architecture

Generation Pipeline

GeneratorFactory::make(documentation) → creates Generator with merged config → Generator::generateDocs() chains:

prepareDirectory() — ensure output dir exists/writable
defineConstants() — define PHP constants from config (usable in annotations)
scanFilesForDocumentation() — swagger-php scans PHP files using ReflectionAnalyser + AttributeAnnotationFactory
populateServers() — injects base path as a Server URL
saveJson() — writes JSON, then SecurityDefinitions::generate() injects security schemes
makeYamlCopy() — optional YAML conversion via symfony/yaml

Custom processors can be positioned relative to any existing processor via scanOptions.processors using ['class' => ..., 'after' => ...] syntax. A CustomGeneratorInterface implementation can be provided via scanOptions.generator_factory to supply a pre-configured OpenApi\Generator.

Service Container Bindings

L5SwaggerServiceProvider binds Generator::class as a factory — each resolution creates a new Generator via GeneratorFactory::make() using the l5-swagger.default documentation name. The GenerateDocsCommand is registered as a singleton under command.l5-swagger.generate.

Routing

Routes are registered dynamically in src/routes.php by iterating all documentation sets. Each set gets up to 4 routes (api UI, docs JSON/YAML, assets, OAuth2 callback), all wrapped with the Config middleware that sets the active documentation context. Route names follow l5-swagger.{documentation}.{type}.

Helpers

swagger_ui_dist_path() resolves swagger-ui asset paths with an allowlist of permitted files. l5_swagger_asset() generates versioned (cache-busted) URLs for those assets.

Testing

Tests use Orchestra Testbench (Tests\Unit\TestCase extends OrchestraTestCase) for a full Laravel environment.

Key patterns:

$this->fileSystem is a PHPUnit mock of Filesystem, injected into Generator via reflection in makeGeneratorWithMockedFileSystem()
setAnnotationsPath() reconfigures the app to use tests/storage/annotations/OpenApi/ fixtures and rebuilds the generator
setCustomDocsFileName() overrides the output filename for JSON/YAML format tests
copyAssets() copies swagger-ui dist into testbench's vendor directory in setUp; tearDown cleans up generated docs
PHPUnit attributes: #[TestDox('...')], #[CoversClass(...)]

Test fixtures live in tests/storage/annotations/OpenApi/ with sample PHP attribute annotations.

Code Style

StyleCI: preset: laravel — enforced automatically
PHPStan: Level 8, analyzes src/ and tests/Unit/, ignores argument.templateType
PHP 8.2+ required; uses constructor property promotion, union types, named arguments
Supports Laravel 11.44+, 12.1+, and 13.0+

Environment Variables

Variable	Purpose
`L5_SWAGGER_GENERATE_ALWAYS`	Regenerate docs on every request (dev mode)
`L5_SWAGGER_GENERATE_YAML_COPY`	Also create YAML version
`L5_SWAGGER_CONST_HOST`	Default host constant for annotations
`L5_SWAGGER_OPEN_API_SPEC_VERSION`	`3.0.0` (default) or `3.1.0`
`L5_SWAGGER_UI_DARK_MODE`	Dark mode for Swagger UI
`SWAGGER_VERSION`	Used in tests to set OpenAPI version

4.2 KiB Raw Blame History