Download the PHP package kr0lik/laravel-dto-to-swagger without Composer

laravel-dto-to-swagger

Overview

laravel-dto-to-swagger is an automatic Swagger documentation generator based on Laravel routing and strongly typed DTOs for request and response data.

💡 No need to manually define schemas, tags, or routes! The documentation is generated entirely based on your route definitions and DTOs. Just rely on your type annotations, and let the package handle the rest.

💡 Integrates with spatie/laravel-data, making Swagger generation seamless and fully automated.

💡 The schema fully reflects your type definitions without manual intervention.

💡 Based on zircote/swagger-php for powerful OpenAPI support.

Installation & Setup

Register the service provider in config/app.php (if needed):

Publish the configuration file (swagger.php):

Configuration

The config file is located at config/swagger.php. You can define multiple configurations using keys (e.g., default, custom-config).

Configuration Options:

• savePath: Path for the generated Swagger YAML file.
• includeMiddlewares, excludeMiddlewares: Define which middlewares to include/exclude.
• includePatterns, excludePatterns: Control route inclusion/exclusion patterns.
• middlewaresToAuth: Define authentication middlewares (e.g., auth:sanctum).
• tagFromControllerName, tagFromControllerFolder, tagFromActionFolder, tagFromMiddlewares: Control Swagger tags generation.
• fileUploadType: Define the class used for file upload with multipart/form-data schema.
• defaultErrorResponseSchemas, requestErrorResponseSchemas: Configure default error response schemas.
• openApi: Base OpenAPI configuration, including:
  • info: API metadata (title, version, description, etc.).
  • servers: List of API servers.
  • components: Reusable elements like security schemes and schemas.

  • etc...

Usage

Ensure that your controllers and DTOs are properly typed.

To ensure correct schema generation, DTOs must implement one of the following interfaces depending on the type of data being described:

`Kr0lik\DtoToSwagger\Contract\JsonRequestInterface` – for JSON request bodies.
`Kr0lik\DtoToSwagger\Contract\QueryRequestInterface` – for query parameters.
`Kr0lik\DtoToSwagger\Contract\HeaderRequestInterface` – for request headers.
`Kr0lik\DtoToSwagger\Contract\JsonResponseInterface` – for JSON responses.

This approach allows you to consolidate all request-related data into a single DTO while maintaining complete Swagger documentation coverage.

Defining Additional Parameters in JsonRequestInterface

Even if a DTO implements JsonRequestInterface (which primarily describes the request body), you can still define query parameters, path parameters, or headers within the same DTO. To do this, use OpenAPI attributes such as:

#[OpenApi\Attributes\Parameter(in: 'query')] – for query parameters.
#[OpenApi\Attributes\Parameter(in: 'path')] – for path parameters.
#[OpenApi\Attributes\Parameter(in: 'header')] – for header parameters.

By implementing the appropriate interface, you enable automatic documentation generation without the need for manual schema definitions.

Update the config/swagger.php file according to your needs.

You can configure multiple configurations (e.g., default, else-one).

If the default config is specified, subsequent configs will be based on it. The default config is optional. The keys can be anything.

Ensure your controllers and actions are properly typed and utilize DTOs (Data Transfer Objects) for request and response data.

Run Swagger generation for default configuration:

This generates a swagger.yaml file with fully automated API documentation.

If you want to generate using a specific configuration (for example, else-one), you can specify it like this:

This generates a swagger-else-one.yaml file from config above.

Example

Automatically handle path parameters, query parameters, and request bodies with DTOs.

Request DTO Example

Response DTO Example

Advanced Customization

Use OpenAPI attributes to refine your documentation:

Request DTO Extend Example

Query Request DTO Extend Example

Header Request DTO Extend Example

Query Response DTO Extend Example

Additional Attributes for Enhanced Schema Customization

In addition to standard OpenAPI attributes, you can leverage specialized attributes from the package to fine-tune the generated documentation and schema definitions:

Kr0lik\DtoToSwagger\Attribute\Context – Specifies additional context for property generation, such as formatting or enum values.
Kr0lik\DtoToSwagger\Attribute\Name – Allows renaming a property in the generated documentation, useful when the DTO property name differs from the expected API field.
Kr0lik\DtoToSwagger\Attribute\Nested – Enables structured query parameters, allowing representation of objects in query strings (e.g., metadata[thing1]=abc&metadata[thing2]=def).
Kr0lik\DtoToSwagger\Attribute\Security – Defines security settings such as authentication mechanisms directly within DTOs or controllers.
Kr0lik\DtoToSwagger\Attribute\Wrap – Wraps the data into a specific structure, useful for APIs that require responses to be enclosed within a defined schema.

Using these attributes ensures that the generated Swagger documentation accurately reflects your API structure while minimizing manual configuration.

See example folder

Develop

docker pull composer:2.2.20

docker run -v .:/app --rm composer:2.2.20 composer install

docker run -v .:/app --rm composer:2.2.20 vendor/bin/php-cs-fixer fix

docker run -v .:/app --rm composer:2.2.20 vendor/bin/phpstan analyse

docker run -v .:/app --rm composer:2.2.20 vendor/bin/composer-unused

See Also

📌 zircote/swagger-php – Base library used.

📌 spatie/laravel-data – Optional integration for DTO management.