PHP code example of bellissimopizza / laravel-swagger-attributes

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

bellissimopizza / laravel-swagger-attributes example snippets

return [
    'title' => 'My API Documentation',
    'description' => 'Documentation for my awesome API',
    'version' => '1.0.0',
    
    // UI configuration - choose between Swagger UI and Redoc
    'ui' => [
        // Which UI to use: 'swagger', 'redoc', or 'both'
        'type' => 'both',
        
        // UI routes
        'swagger_route' => 'api/documentation',
        'redoc_route' => 'api/redoc',
        
        // Redoc options
        'redoc' => [
            'theme' => 'light',  // light, dark
            'hide_download_button' => false,
            'expand_responses' => 'all', // all, success, none
        ],
        
        // Swagger UI options
        'swagger' => [
            'deep_linking' => true,
            'doc_expansion' => 'list', // list, full, none
        ],
    ],
    
    // ...other configuration options
];

use BellissimoPizza\SwaggerAttributes\Attributes\OpenApi;
use BellissimoPizza\SwaggerAttributes\Attributes\OpenApiRequestBody;
use BellissimoPizza\SwaggerAttributes\Attributes\OpenApiException;

class UserController extends Controller
{
    #[OpenApi(
        tag: 'Users',
        summary: 'Create new user',
        method: 'POST'
    )]
    #[OpenApiRequestBody(
        requestClass: StoreUserRequest::class
    )]
    #[OpenApiException(
        statusCode: 422,
        message: 'Validation failed'
    )]
    #[OpenApiException(
        statusCode: 500,
        message: 'Server error'
    )]
    public function store(StoreUserRequest $request)
    {
        // Your controller logic here
    }
}

#[ApiSwagger(
    tag: 'Users',                  // Used for grouping endpoints
    summary: 'Create new user',    // Short summary
    description: 'Detailed...',    // Optional longer description
    method: 'POST',                // HTTP method (GET, POST, PUT, DELETE, etc.) - automatically detected from routes if not specified
    path: '/api/users',            // Optional custom path (if different from route)
    deprecated: false              // Mark as deprecated
)]

#[ApiSwaggerRequestBody(
    requestClass: StoreUserRequest::class,  // Laravel FormRequest class
    rules: [],                              // Manual rules (if no request class)
    contentType: 'application/json',        // Content type
    

#[ApiSwaggerException(
    statusCode: 404,                      // HTTP status code
    message: 'User not found',            // Error message
    exceptionClass: UserNotFoundException::class, // Optional exception class
    responseSchema: []                    // Optional custom response schema
)]

#[ApiSwaggerResponse(
    statusCode: 200,                     // HTTP status code
    description: 'Successful operation',  // Response description
    model: User::class,                   // Eloquent model (auto-generates schema from DB)
    resource: UserResource::class,        // Laravel API Resource (overrides model properties)
    responseType: ResponseType::SINGLE,   // SINGLE, COLLECTION, or PAGINATED
    contentType: 'application/json'       // Content type
)]

// Or use a custom schema
#[ApiSwaggerResponse(
    statusCode: 200,
    schema: [
        'type' => 'object',
        'properties' => [
            'id' => ['type' => 'integer'],
            'name' => ['type' => 'string']
        ]
    ]
)]

// Basic API Resource usage
#[ApiSwaggerResponse(
    statusCode: HttpStatusCode::OK,
    resource: UserResource::class,
    responseType: ResponseType::SINGLE
)]

// Combine with a model for additional type information
#[ApiSwaggerResponse(
    statusCode: HttpStatusCode::OK,
    model: User::class,            // Base model schema 
    resource: UserResource::class,  // Resource overrides model properties
    responseType: ResponseType::COLLECTION
)]

// API Resource with nested model placeholder
#[ApiSwaggerResponse(
    statusCode: HttpStatusCode::OK,
    model: User::class,
    resource: UserResource::class,
    schema: [
        'success' => OpenApiDataType::BOOLEAN,
        'data' => 'model'  // This will be replaced with the resource schema
    ]
)]

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @property int $id User ID
     * @property string $name User's full name
     * @property string $email User's email address
     * @property array $permissions User's permissions
     * @property string $created_at Creation timestamp
     * 
     * @return array
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'permissions' => $this->permissions,
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}

use BellissimoPizza\SwaggerAttributes\Enums\OpenApiDataType;

#[ApiSwaggerQueryParam(
    name: 'filter',                     // Parameter name
    type: OpenApiDataType::STRING,      // Data type (STRING, INTEGER, BOOLEAN, etc.)
    description: 'Filter results',       // Parameter description
            // Additional schema properties
)]
#[ApiSwaggerQueryParam(
    name: 'sort',
    type: OpenApiDataType::STRING,
    description: 'Sort field',
    example: 'created_at'
)]
#[ApiSwaggerQueryParam(
    name: 'page',
    type: OpenApiDataType::INTEGER,
    description: 'Page number for pagination',
    default: 1
)]
public function index(Request $request)
{
    // Your controller logic here
}

'ui' => [
    'type' => 'both', // Options: 'swagger', 'redoc', 'both'
],

/**
 * @property int $id
 * @property string $name
 * @property-read \Carbon\Carbon $created_at
 * @property-write array $settings
 */
class User extends Model
{
    // ...model code
}

use BellissimoPizza\SwaggerAttributes\Enums\OpenApiDataType;

#[ApiSwaggerResponse(
    statusCode: 200,
    schema: [
        'id' => OpenApiDataType::INTEGER,
        'name' => OpenApiDataType::STRING,
        'created_at' => OpenApiDataType::DATE_TIME,
        'is_active' => OpenApiDataType::BOOLEAN,
    ]
)]

#[ApiSwagger(
    method: HttpMethod::POST,
    path: '/api/users',
    tag: 'Users',
    summary: 'Create a new user'
)]
#[ApiSwaggerRequestBody(
    requestClass: StoreUserRequest::class
)]
#[ApiSwaggerResponse(
    statusCode: HttpStatusCode::CREATED,
    model: User::class
)]
#[ApiSwaggerValidationErrorResponse(
    description: 'Validation failed for the submitted form data'
)]
public function store(StoreUserRequest $request)
{
    // ...
}

bash
php artisan swagger:generate

bash
# Generate JSON (default)
php artisan swagger:generate --output=public/api-docs/swagger.json --format=json

# Generate YAML
php artisan swagger:generate --output=public/api-docs/swagger.yaml --format=yaml