Download the PHP package savionicodemos/laravel-auto-swagger without Composer

Laravel Auto Swagger Docs

Simple to use OAS3 compatible documentation generator.
Also includes Swagger UI.

About

This package is heavily inspired by the Mezatsong/laravel-swagger-docs.

The set of functions that this package has are included:

1. OAS3 support (with constant verifications to ensure syntax and compatibility)
2. Custom decorators
3. Custom responses with support for multiple content types per status code
4. Custom Schemas with @Schema and @Property annotations
5. Custom Schema builders
6. Automatic Parameters generation based on path and Form Request classes
7. Inclusion of Swagger UI with option to select between different UI drivers
8. Automatic Schema generation from Eloquent Models or custom Schema classes
9. Generate operation tags based on route prefix or controller name
10. Developer warnings for undefined tags and unreferenced custom schemas

Installation

Install package through composer

Publish configuration files and views

Edit the swagger.php configuration file for your liking

Usage

Laravel Auto Swagger Docs works based on recommended practices by Laravel. It will parse your routes and generate a path object for each one. If you inject Form Request classes in your controller's actions as request validation, it will also generate the parameters for each request that has them. For the parameters, it will take into account whether the request is a GET/HEAD/DELETE or a POST/PUT/PATCH request and make its best guess as to the type of parameter object it should generate. It will also generate the path parameters if your route contains them. Finally, this package will also scan any documentation you have in your action methods and add it as summary and description to that path, along with any appropriate annotations such as @deprecated.

Command line

Generating the swagger documentation is easy, simply run php artisan swagger:generate in your project root. The output of the command will be stored in your storage path linked in the config file.

If you wish to generate docs for a subset of your routes, you can pass a filter using --filter, for example: php artisan swagger:generate --filter="/api"

You can also configure your swagger.php file to always regenerate when accessing Swagger UI, or by adding this line in your .env: SWAGGER_GENERATE_ALWAYS=true

By default, the package prints documentation in JSON format. If you want YAML format, override it using the --format flag. Make sure to have the yaml extension installed if you choose to do so.

Format options are:

• json
• yaml

[!NOTE] During generation the command will print yellow warnings in the terminal for any issues found (such as undefined tags or unreferenced schemas). These are also written to the Laravel log. See the Developer Warnings section for details.

Annotations syntax

The annotations are written in the PHPDoc block of your controller methods. The syntax is as follows:

The syntax is basically JSON inside a comment block. Follow the JSON syntax strictly.

@Request() decorator

You can have only one @Request() decorator per method.

Supported @Request keys

@Response() decorator

You can have multiple @Response() decorators on the same method.

Supported @Response keys

ref formats

[!NOTE] See all available schema builders or create your own — explore swagger.schema_builders in the config.

Binary / file download responses

Use content_type to declare a non-JSON response body (e.g. PDF, CSV, image):

Multiple content types for the same status code

You can stack multiple @Response decorators with the same code to declare several content types. Each adds its own entry under the response without overwriting the others:

[!NOTE] The description is taken from the first @Response that declares it for a given code. For multiple content types without content_type, use ref on each to point to different schemas.

Custom Validators (Form Request rules)

These rules are added directly to your Form Request rules() array. They are purely for documentation purposes — they do not affect Laravel's validation behaviour (except swagger_min and swagger_max which optionally can).

[!NOTE] These rules are registered by the package's service provider. There is no extra setup required.

[!NOTE] When a Form Request produces at least one visible parameter, the generated requestBody is automatically marked as required: true in the spec. If all fields are hidden via swagger_hidden, no requestBody is emitted at all.

swagger_hidden

Completely hides a field (and any of its nested children) from the generated documentation. Useful for internal fields or fields only used for conditional logic.

swagger_required

Overrides the required status for a parameter in the documentation, independently of the actual Laravel validation rule. Useful when a field is conditionally required at runtime but should always appear as required (or optional) in the docs.

swagger_default

Sets the default value shown for the parameter in the documentation.

swagger_example

Sets an example value for the parameter in the documentation.

[!NOTE] swagger_default communicates that the application uses this value when the field is absent. swagger_example just illustrates how the field should be filled — it has no runtime meaning.

swagger_description

Sets the description text for the parameter in the documentation.

swagger_min

Documents a minimum value. Optionally also enforces it at runtime by appending :fail.

swagger_max

Documents a maximum value. Optionally also enforces it at runtime by appending :fail.

Automatic type inference from Laravel rules

The package reads standard Laravel validation rules to automatically infer OpenAPI types and formats:

Custom Schemas

Custom Schema classes let you define reusable OpenAPI schemas that are not tied to an Eloquent model. They are plain PHP classes with typed properties and optional @Schema / @Property docblock annotations.

Setup

Create your schema classes inside the folder configured in swagger.schemas (default: app/Swagger/Schemas). Each class in that folder (and any subdirectories) is automatically discovered and registered in components.schemas.

The property names become the schema property names. PHP types are automatically mapped to OpenAPI types:

DateTime auto-inference

When a property's PHP type is DateTime, DateTimeImmutable, DateTimeInterface, or any class that implements DateTimeInterface (including Carbon), the package automatically sets type: string and format: date-time — no annotation needed:

Static properties as examples

If a property is declared static with a default value, that value is used as the example in the generated schema:

@Schema annotation

Use @Schema on the class to declare which properties are required in the OpenAPI schema. Only fields that exist as properties on the class are included in the required array.

@Property annotation

Use @Property on individual properties to override or extend the automatically inferred type information.

Supported @Property keys

@Property ref examples

When both ref and nullable or description are present, the output uses allOf to comply with the OpenAPI spec:

@Property raw — verbatim injection

Use raw when you need full control and none of the other keys are sufficient:

Multiple schemas directories

The schemas key in each page config accepts either a single path or an array of paths. This is useful for modularized projects:

Tags

Automatic tag generation

Tags are generated automatically based on the default_tags_generation_strategy page config:

You can always override the auto-generated tag per operation using the tags key in @Request.

Declaring global tags

Define global tags in the page config to attach descriptions to each tag group. These appear in Swagger UI's sidebar:

Developer Warnings

During swagger:generate, the package prints warnings to the terminal (in yellow, using Laravel's $this->warn()) and to the Laravel log whenever it detects issues worth your attention. Nothing breaks — these are advisory only.

Undefined tag warning

Fires when an operation uses a tag that is not declared in the global tags array. Only active when at least one global tag is configured (if tags is empty, the check is skipped entirely to avoid noise on unconfigured projects).

Fix: add the missing tag to the tags array in your page config, or remove the tags entry from the @Request annotation if it was a typo.

Unreferenced custom schema warning

Fires when a class from your schemas folder is generated into components.schemas but never referenced by any $ref anywhere in the documentation (neither in a path operation response nor in another schema's properties). Eloquent model schemas are excluded from this check — it only applies to classes you explicitly placed in the schemas folder.

Fix: either delete the unused schema class, or add a @Response with "ref": "LegacyPayload" to the relevant controller methods.