Download the PHP package bellissimopizza/laravel-swagger-attributes without Composer

Laravel OpenApi Attributes

Version 4.0.0 now available with full Laravel API Resource support! Generate accurate OpenAPI schemas directly from your Resource classes.

This package provides a clean way to generate Swagger/OpenAPI documentation for your Laravel API using PHP 8 Attributes instead of annotations.

Features

• Use modern PHP 8 Attributes to document your API endpoints
• Leverage PHP 8 Enums for type safety and standardization
• [NEW in v4.0.0] Full support for Laravel API Resources in response schema generation
• [NEW in v4.0.0] Extract property types from Resource PHPDoc comments and method analysis
• Automatically extract validation rules from Laravel Form Request classes
• Document API exceptions with status codes and error messages
• Command-line tool to scan routes and generate Swagger documentation
• Built-in Swagger UI and Redoc UI for viewing documentation
• Extract property types from Laravel IDE Helper PHPDoc comments
• Support for query parameters with repeatable attributes
• Fully customizable through configuration

Requirements

• PHP 8.0 or higher
• Laravel 8.0 or higher

Installation

You can install the package via composer:

After installing, publish the configuration and assets:

Usage

Basic Configuration

First, configure the package in config/swagger-attributes.php:

Documenting API Endpoints

Use PHP attributes to document your API endpoints. Here's a simple example:

Available Attributes

ApiSwagger

The main attribute for documenting API endpoints:

ApiSwaggerRequestBody

Document request body and validation rules:

ApiSwaggerException

Document possible exceptions (can be repeated for multiple exceptions):

ApiSwaggerResponse

Document response data with automatic schema generation from Eloquent models:

Using Laravel API Resources

The package now supports Laravel API Resources for response schema generation. This provides more flexibility when your API responses don't directly match your database models.

The package automatically analyzes your API Resource classes to extract property information by:

1. Using PHPDoc annotations in your resource's toArray() method
2. Analyzing the resource structure when a model is provided
3. Supporting nested models and resource structures

For best results, document your API Resource properties using PHPDoc:

ApiSwaggerQueryParam

Document query parameters for filtering, sorting, and pagination (can be repeated for multiple parameters):

Generating Documentation

Run the command to scan your routes and generate Swagger documentation:

By default, this will save the documentation to storage/api-docs/swagger.json. You can specify a custom output path and format (JSON or YAML):

Viewing Documentation

Once generated, you can view your documentation at the following URLs:

• Swagger UI: /api/documentation (or your custom route)
• Redoc UI: /api/redoc (or your custom route)

You can configure which UI is enabled in the configuration file:

IDE Helper Integration

This package can read Laravel IDE Helper generated PHPDoc comments to improve the accuracy of property types in your model schemas. If you have Laravel IDE Helper installed and have generated model docs, the package will automatically read the @property, @property-read, and @property-write annotations to determine property types.

For example, if your model has:

These types will be used to generate more accurate OpenAPI schemas compared to just using database column types.

Enhanced Response Schemas

The package now properly formats response schemas according to OpenAPI 3.0 specifications. When using custom response schemas, you can use PHP 8 enums to define data types:

The enum values are automatically converted to proper OpenAPI type and format objects in the schema.

The file extension will be automatically added if not specified in the output path. Old documentation files are automatically deleted before generating new ones to ensure clean output.

Additional Improvements

HTTP Method Normalization

The package now automatically normalizes HTTP methods to lowercase in the OpenAPI paths to ensure compatibility with all OpenAPI consumers and prevent duplicate endpoints with different method casing.

Auto-cleaning of Documentation Files

When generating new documentation, any existing Swagger JSON/YAML files are automatically deleted first. This ensures you always have a clean, up-to-date documentation file without artifacts from previous generations.

Direct File Access

The package now reads documentation files directly from storage instead of requiring them to be publicly accessible via URLs. This improves security by eliminating the need for symbolic links between storage and public directories, and simplifies deployment across different environments.

You can view your API documentation at the route you specified in the configuration file.

Validation Error Responses

The package now automatically adds a standard validation error response (HTTP 422) to endpoints that use validation rules through either:

1. Form Request classes via ApiSwaggerRequestBody
2. Inline validation rules in ApiSwaggerRequestBody

This validation error schema matches Laravel's default validation error format:

You can also manually add a validation error response to any endpoint by using the ApiSwaggerValidationErrorResponse attribute:

The ValidationError schema is automatically registered in the OpenAPI components section and can be reused across your API documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.

laravel-swagger-attributes