Configuration

composer require langsys/openapi-docs-generator

PHP 8.1+ Laravel 10 / 11

All configuration lives in config/openapi-docs.php:

documentations — per-set overrides (file names, scan paths)
defaults — shared settings inherited by all sets

Every key under defaults can be overridden per set via deep merge (associative arrays merge recursively; scalars and indexed arrays are replaced).

Multiple documentation sets

Useful for API versioning or separating public/internal APIs:

'documentations' => [
    'v1' => [
        'paths' => [
            'docs_json' => 'v1-api-docs.json',
            'annotations' => [app_path('Http/Controllers/V1'), app_path('DataObjects/V1')],
        ],
    ],
    'v2' => [
        'paths' => [
            'docs_json' => 'v2-api-docs.json',
            'annotations' => [app_path('Http/Controllers/V2'), app_path('DataObjects/V2')],
        ],
    ],
],

The annotations directories are scanned for both controller annotations and Data subclasses.

Filtered documentation sets

A set can emit only a subset of your API — for example an integration spec containing just the endpoints an API key can call. Operations are matched to their Laravel route and selected by a pluggable filter. The default discriminator is route middleware — ground truth, unlike hand-written security annotations, which drift from what your routes actually enforce.

'documentations' => [
    'integration' => [
        'paths'  => ['docs_json' => 'api-docs-integration.json'],
        'filter' => [
            'include' => [
                ['middleware' => 'auth.apikey'],
            ],
        ],
        'security_override' => [['apiKey' => []]],
        'info' => [
            'title'       => 'Langsys Integration API',
            'description' => 'The API-key-accessible subset of the Langsys API.',
        ],
    ],
],

Filtered set 'integration': kept 16, dropped 133 operation(s).

This is how the docs site’s integration view is produced.

Operations are resolved to routes action-first (controller action maps exactly to the route). Closures and path-only annotations fall back to HTTP method + path. The filter inspects fully-resolved middleware (groups expanded, aliases resolved).

include / exclude descriptors: middleware, tag, path (glob), operationId, or a custom OperationFilter class. An empty include means all operations are candidates. Unmatched operations are excluded by default and listed by the command.

security_override forces the security requirement on every surviving operation and restricts components/securitySchemes to the schemes it names. info deep-merges over the scanned @OA\Info for that set only.

Clean output (automatic pruning)

Every generated document is pruned to only the schemas, parameters, responses, security schemes and tags reachable from its operations. Always on for filtered sets. Opt out per set with 'prune_unused_components' => false to keep every discovered DTO.

Security definitions

Inject OpenAPI security schemes and global security requirements from config. If you define a scheme with the same name both in config and via a @OA\SecurityScheme annotation, the annotation version wins. These settings control what appears in the spec; they are separate from Thunder Client auth config.

YAML, servers, constants, processors

'generate_yaml_copy' => true (or OPENAPI_GENERATE_YAML=true) writes YAML alongside JSON
paths.base adds a servers entry
constants define PHP constants referenced inside @OA\* annotations
scan_options.processors run after swagger-php parses annotations — the usual use is controlling tag order in Swagger UI. Scaffold with openapi:make-processor and register the class in config.

Feedback