Download the PHP package stackmasteraliza/laravel-api-response without Composer

Laravel API Toolkit

stackmasteraliza/laravel-api-response

The all-in-one Laravel API solution: Standardized Responses + Auto-generated Swagger Docs + Export to Postman & Insomnia

A clean and consistent API response builder for Laravel applications. This package provides a simple and elegant way to build standardized JSON responses for your APIs with zero-config OpenAPI documentation.

Developed by Aliza Ali
_{Creator & Maintainer}

Features

• Consistent API response structure
• HTTP status code included in response body
• Fluent interface for building responses
• Built-in methods for common HTTP status codes
• Automatic pagination metadata (including cursor pagination)
• Auto-generated OpenAPI/Swagger documentation
• API versioning support (v1, v2, etc.) with version switcher UI
• Built-in WebSocket tester in Swagger UI
• Export to Postman, Insomnia, JSON & YAML
• Response macros for custom response types
• Testing helpers for API assertions
• Exception handler for consistent error responses
• Facade and Trait support
• Fully customizable via config

Installation

You can install the package via composer:

The package will automatically register itself.

Publish Configuration (Optional)

Usage

Using the Facade

Using the Trait

Available Methods

Success Responses

Error Responses

Response Structure

Success Response

Paginated Response

Cursor Paginated Response

Cursor pagination is more efficient for large datasets:

Error Response

Exception Handling

To use the built-in exception handler, update your bootstrap/app.php (Laravel 11+):

Or for Laravel 10, update your app/Exceptions/Handler.php:

Middleware

Use the ForceJsonResponse middleware to ensure all API responses are JSON:

Adding Custom Data

Response Macros

Define reusable custom response types using macros:

Usage:

Testing Helpers

The package provides convenient testing assertions for your API tests:

Available Test Assertions

OpenAPI/Swagger Documentation

The package automatically generates OpenAPI 3.0 documentation from your API routes with a beautiful, modern dark-themed UI - no additional coding required!

Export to Multiple Formats

Export your API documentation to Postman, Insomnia, JSON, or YAML with a single click.

Built-in Authorization

Easily configure Bearer Token or API Key authentication directly from the UI.

WebSocket Tester

Test WebSocket connections directly from the documentation with real-time message sending and receiving.

Zero-Configuration Auto-Generation

The package intelligently generates documentation by:

• Detecting ApiResponse method calls - Scans your controller code for ApiResponse::success(), ApiResponse::created(), etc. and automatically determines response status codes
• Extracting FormRequest validation rules (optional) - If your controller methods use FormRequest classes, validation rules are automatically converted to OpenAPI request body schemas
• Inferring from route patterns - Resource controller methods (index, show, store, update, destroy) get meaningful summaries and descriptions
• Detecting pagination - Automatically identifies paginated responses when using ->paginate() or ->cursorPaginate()

No FormRequest or PHP attributes required! Just write your Laravel code normally and get instant API documentation.

Note: FormRequest classes are completely optional. If you don't use them, the package will still generate documentation - it will just show a generic request body schema for POST/PUT/PATCH endpoints. Using FormRequest simply provides richer, more detailed request body documentation.

View Documentation

Simply visit /api-docs in your browser to see the interactive Swagger UI:

Custom Swagger UI Features

The package includes a beautifully designed custom Swagger UI with:

• Theme Support - Dark, Light, and Auto (system preference) themes with toggle button
• Custom Branding - Display your app name and logo in the header
• Hero Section - Welcome message with live API statistics (endpoints, categories, schemas)
• Search Bar - Filter APIs by path, method, or description
• Authorization Modal - Support for Bearer Token and API Key authentication with localStorage persistence
• Export Options - Export API documentation in multiple formats (JSON, YAML, Postman, Insomnia)
• Responsive Design - Works great on desktop and mobile devices
• Method Badges - Color-coded HTTP method indicators (GET, POST, PUT, DELETE, PATCH)

Export API Documentation

Export your API documentation directly from the Swagger UI to import into your preferred tools. Click the Export button in the header to access the following formats:

OpenAPI Specification

• OpenAPI JSON - Standard JSON format compatible with any OpenAPI 3.0 tool
• OpenAPI YAML - Human-readable YAML format for easier editing and version control

API Client Collections

• Postman Collection (v2.1) - Ready to import into Postman with:

  • Organized folders by API tags/categories
  • Pre-configured base URL as collection variable
  • Request bodies with auto-generated example data
  • Query parameters, path variables, and headers
• Insomnia Collection (v4) - Ready to import into Insomnia with:
  • Workspace and environment setup
  • Organized request groups by tags
  • Base URL as environment variable
  • Full request configuration

All exports are generated client-side for instant downloads with no server load.

Customization

Configure the Swagger UI appearance in your .env file:

Or in your config file:

API Endpoints

Generate Static File

Generate a static OpenAPI JSON file:

This creates public/api-docs/openapi.json that you can use with any OpenAPI-compatible tool.

Enhanced Documentation with Attributes (Optional)

For more detailed or customized documentation, you can optionally add PHP attributes to your controller methods:

Available Attributes

Built-in Schema References

Use these in #[ApiResponse(ref: '...')]:

• SuccessResponse - Standard success response
• ErrorResponse - Standard error response
• PaginatedResponse - Paginated list response
• ValidationErrorResponse - Validation error with field errors

Configuration

Disabling Status Code in Response Body

If you prefer not to include the status code in the response body, you can disable it:

Or in your config file:

API Versioning

The package supports versioned API documentation. When enabled, it auto-detects version prefixes from your routes (e.g., api/v1/*, api/v2/*) and generates separate OpenAPI specs for each version with a version switcher in the Swagger UI.

Enable Versioning

Add to your .env file:

Or in your config file (config/api-response.php):

Custom Version Definitions

For more control, you can define custom version patterns:

Versioned Endpoints

When versioning is enabled, the following endpoints become available:

WebSocket Testing

The Swagger UI includes a built-in WebSocket tester for testing real-time connections directly from the documentation.

Features

• Connect to any WebSocket endpoint
• Send and receive messages in real-time
• Pre-built message templates (Subscribe, Unsubscribe, Ping, Client Event)
• Message history with timestamps
• Connection state persistence

Configuration

Click the WebSocket button in the Swagger UI header to open the tester.

Testing

Contributing

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

License

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