{"id":35211108,"url":"https://github.com/stackmasteraliza/laravel-api-response-builder","last_synced_at":"2026-04-07T13:32:17.383Z","repository":{"id":331266931,"uuid":"1124724785","full_name":"stackmasteraliza/laravel-api-response-builder","owner":"stackmasteraliza","description":"A clean and consistent API response builder for Laravel applications with fluent interface, pagination support, and exception handling.","archived":false,"fork":false,"pushed_at":"2026-03-13T04:22:32.000Z","size":794,"stargazers_count":29,"open_issues_count":7,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-13T12:17:07.831Z","etag":null,"topics":["api","api-builder","api-response","composer-package","json","laravel","laravel-package","laravel10","laravel11","laravel12","opensource","php","php8","response-builder","rest","rest-api","restful","stackmasteraliza"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/stackmasteraliza/laravel-api-response","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackmasteraliza.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-29T14:03:25.000Z","updated_at":"2026-03-03T12:57:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stackmasteraliza/laravel-api-response-builder","commit_stats":null,"previous_names":["stackmasteraliza/laravel-api-response-builder"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/stackmasteraliza/laravel-api-response-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackmasteraliza%2Flaravel-api-response-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackmasteraliza%2Flaravel-api-response-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackmasteraliza%2Flaravel-api-response-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackmasteraliza%2Flaravel-api-response-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackmasteraliza","download_url":"https://codeload.github.com/stackmasteraliza/laravel-api-response-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackmasteraliza%2Flaravel-api-response-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31515144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-builder","api-response","composer-package","json","laravel","laravel-package","laravel10","laravel11","laravel12","opensource","php","php8","response-builder","rest","rest-api","restful","stackmasteraliza"],"created_at":"2025-12-29T18:24:44.824Z","updated_at":"2026-04-07T13:32:17.376Z","avatar_url":"https://github.com/stackmasteraliza.png","language":"PHP","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/logo-banner.svg\" alt=\"Laravel API Toolkit\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tests-Passing-brightgreen\" alt=\"Tests\"\u003e\n  \u003ca href=\"https://packagist.org/packages/stackmasteraliza/laravel-api-response\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/stackmasteraliza/laravel-api-response.svg\" alt=\"Latest Version on Packagist\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagist.org/packages/stackmasteraliza/laravel-api-response\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/stackmasteraliza/laravel-api-response.svg\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://doi.org/10.5281/zenodo.18204415\"\u003e\u003cimg src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.18204415.svg\" alt=\"DOI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagist.org/packages/stackmasteraliza/laravel-api-response\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/stackmasteraliza/laravel-api-response.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://laravel-news.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Laravel%20News-Featured-orange\" alt=\"Laravel News\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PHP-8.1%2B-777BB4\" alt=\"PHP Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Laravel-10%20%7C%2011%20%7C%2012-FF2D20\" alt=\"Laravel Version\"\u003e\n\u003c/p\u003e\n\n# Laravel API Toolkit\n\n### `stackmasteraliza/laravel-api-response`\n\n\u003e The all-in-one Laravel API solution: Standardized Responses + Auto-generated Swagger Docs + Export to Postman \u0026 Insomnia\n\nA 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.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/stackmasteraliza\"\u003e\n    \u003cimg src=\"https://images.weserv.nl/?url=github.com/stackmasteraliza.png\u0026w=80\u0026h=80\u0026fit=cover\u0026mask=circle\" alt=\"Aliza Ali\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003cb\u003eDeveloped by \u003ca href=\"https://github.com/stackmasteraliza\"\u003eAliza Ali\u003c/a\u003e\u003c/b\u003e\n  \u003cbr\u003e\n  \u003csub\u003eCreator \u0026 Maintainer\u003c/sub\u003e\n\u003c/p\u003e\n\n## Features\n\n- Consistent API response structure\n- HTTP status code included in response body\n- Fluent interface for building responses\n- Built-in methods for common HTTP status codes\n- Automatic pagination metadata (including cursor pagination)\n- **Auto-generated OpenAPI/Swagger documentation**\n- **API versioning support (v1, v2, etc.) with version switcher UI**\n- **Built-in WebSocket tester in Swagger UI**\n- **Export to Postman, Insomnia, JSON \u0026 YAML**\n- Response macros for custom response types\n- Testing helpers for API assertions\n- Exception handler for consistent error responses\n- Facade and Trait support\n- Fully customizable via config\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require stackmasteraliza/laravel-api-response\n```\n\nThe package will automatically register itself.\n\n### Publish Configuration (Optional)\n\n```bash\nphp artisan vendor:publish --tag=api-response-config\n```\n\n## Usage\n\n### Using the Facade\n\n```php\nuse Stackmasteraliza\\ApiResponse\\Facades\\ApiResponse;\n\n// Success response\nreturn ApiResponse::success($data, 'Data retrieved successfully');\n\n// Error response\nreturn ApiResponse::error('Something went wrong', 400);\n\n// Created response (201)\nreturn ApiResponse::created($user, 'User created successfully');\n\n// Not found response (404)\nreturn ApiResponse::notFound('User not found');\n\n// Validation error response (422)\nreturn ApiResponse::validationError([\n    'email' =\u003e ['The email field is required.'],\n    'name' =\u003e ['The name field is required.'],\n]);\n```\n\n### Using the Trait\n\n```php\nuse Stackmasteraliza\\ApiResponse\\Traits\\HasApiResponse;\n\nclass UserController extends Controller\n{\n    use HasApiResponse;\n\n    public function index()\n    {\n        $users = User::paginate(15);\n\n        return $this-\u003esuccess($users, 'Users retrieved successfully');\n    }\n\n    public function store(Request $request)\n    {\n        $user = User::create($request-\u003evalidated());\n\n        return $this-\u003ecreated($user, 'User created successfully');\n    }\n\n    public function show(User $user)\n    {\n        return $this-\u003esuccess($user);\n    }\n\n    public function destroy(User $user)\n    {\n        $user-\u003edelete();\n\n        return $this-\u003enoContent();\n    }\n}\n```\n\n### Available Methods\n\n#### Success Responses\n\n| Method | Status Code | Description |\n|--------|-------------|-------------|\n| `success($data, $message, $statusCode)` | 200 | General success response |\n| `created($data, $message)` | 201 | Resource created |\n| `accepted($data, $message)` | 202 | Request accepted for processing |\n| `noContent()` | 204 | No content to return |\n\n#### Error Responses\n\n| Method | Status Code | Description |\n|--------|-------------|-------------|\n| `error($message, $statusCode, $errors)` | Variable | General error response |\n| `badRequest($message, $errors)` | 400 | Bad request |\n| `unauthorized($message)` | 401 | Unauthorized |\n| `forbidden($message)` | 403 | Forbidden |\n| `notFound($message)` | 404 | Resource not found |\n| `methodNotAllowed($message)` | 405 | Method not allowed |\n| `conflict($message, $errors)` | 409 | Conflict |\n| `unprocessable($message, $errors)` | 422 | Unprocessable entity |\n| `validationError($errors, $message)` | 422 | Validation failed |\n| `tooManyRequests($message, $retryAfter)` | 429 | Too many requests |\n| `serverError($message)` | 500 | Internal server error |\n| `serviceUnavailable($message)` | 503 | Service unavailable |\n\n### Response Structure\n\n#### Success Response\n\n```json\n{\n    \"status_code\": 200,\n    \"success\": true,\n    \"message\": \"Data retrieved successfully\",\n    \"data\": {\n        \"id\": 1,\n        \"name\": \"John Doe\",\n        \"email\": \"john@example.com\"\n    }\n}\n```\n\n#### Paginated Response\n\n```json\n{\n    \"status_code\": 200,\n    \"success\": true,\n    \"message\": \"Users retrieved successfully\",\n    \"data\": [\n        {\"id\": 1, \"name\": \"John Doe\"},\n        {\"id\": 2, \"name\": \"Jane Doe\"}\n    ],\n    \"meta\": {\n        \"current_page\": 1,\n        \"per_page\": 15,\n        \"total\": 50,\n        \"last_page\": 4,\n        \"from\": 1,\n        \"to\": 15,\n        \"path\": \"http://example.com/api/users\",\n        \"links\": {\n            \"first\": \"http://example.com/api/users?page=1\",\n            \"last\": \"http://example.com/api/users?page=4\",\n            \"prev\": null,\n            \"next\": \"http://example.com/api/users?page=2\"\n        }\n    }\n}\n```\n\n#### Cursor Paginated Response\n\nCursor pagination is more efficient for large datasets:\n\n```php\n$users = User::cursorPaginate(15);\nreturn ApiResponse::success($users, 'Users retrieved successfully');\n```\n\n```json\n{\n    \"status_code\": 200,\n    \"success\": true,\n    \"message\": \"Users retrieved successfully\",\n    \"data\": [\n        {\"id\": 1, \"name\": \"John Doe\"},\n        {\"id\": 2, \"name\": \"Jane Doe\"}\n    ],\n    \"meta\": {\n        \"per_page\": 15,\n        \"next_cursor\": \"eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0\",\n        \"prev_cursor\": null,\n        \"path\": \"http://example.com/api/users\",\n        \"links\": {\n            \"next\": \"http://example.com/api/users?cursor=eyJpZCI6MTUuLi4\",\n            \"prev\": null\n        }\n    }\n}\n```\n\n#### Error Response\n\n```json\n{\n    \"status_code\": 422,\n    \"success\": false,\n    \"message\": \"Validation failed\",\n    \"errors\": {\n        \"email\": [\"The email field is required.\"],\n        \"name\": [\"The name field is required.\"]\n    }\n}\n```\n\n### Exception Handling\n\nTo use the built-in exception handler, update your `bootstrap/app.php` (Laravel 11+):\n\n```php\nuse Stackmasteraliza\\ApiResponse\\Exceptions\\ApiExceptionHandler;\n\n-\u003ewithExceptions(function (Exceptions $exceptions) {\n    $exceptions-\u003erender(function (Throwable $e, Request $request) {\n        $handler = new ApiExceptionHandler();\n        return $handler-\u003ehandle($e, $request);\n    });\n})\n```\n\nOr for Laravel 10, update your `app/Exceptions/Handler.php`:\n\n```php\nuse Stackmasteraliza\\ApiResponse\\Exceptions\\ApiExceptionHandler;\n\npublic function render($request, Throwable $exception)\n{\n    $handler = new ApiExceptionHandler();\n    $response = $handler-\u003ehandle($exception, $request);\n\n    if ($response) {\n        return $response;\n    }\n\n    return parent::render($request, $exception);\n}\n```\n\n### Middleware\n\nUse the `ForceJsonResponse` middleware to ensure all API responses are JSON:\n\n```php\n// In your route file or middleware group\nuse Stackmasteraliza\\ApiResponse\\Http\\Middleware\\ForceJsonResponse;\n\nRoute::middleware([ForceJsonResponse::class])-\u003egroup(function () {\n    // Your API routes\n});\n```\n\n### Adding Custom Data\n\n```php\nreturn ApiResponse::success($user)\n    -\u003ewithData('token', $token)\n    -\u003ewithHeader('X-Custom-Header', 'value');\n```\n\n### Response Macros\n\nDefine reusable custom response types using macros:\n\n```php\n// In your AppServiceProvider boot() method\nuse Stackmasteraliza\\ApiResponse\\Facades\\ApiResponse;\n\nApiResponse::macro('banned', function (string $reason = 'Account suspended') {\n    return $this-\u003eerror($reason, 403);\n});\n\nApiResponse::macro('maintenance', function () {\n    return $this-\u003eerror('Service under maintenance', 503);\n});\n```\n\nUsage:\n\n```php\nreturn ApiResponse::banned('Your account has been suspended');\nreturn ApiResponse::maintenance();\n```\n\n### Testing Helpers\n\nThe package provides convenient testing assertions for your API tests:\n\n```php\nuse Tests\\TestCase;\n\nclass UserControllerTest extends TestCase\n{\n    public function test_can_list_users()\n    {\n        $response = $this-\u003egetJson('/api/users');\n\n        $response-\u003eassertApiSuccess()\n                 -\u003eassertApiStatusCode(200)\n                 -\u003eassertApiMessage('Users retrieved successfully')\n                 -\u003eassertApiHasData()\n                 -\u003eassertApiPaginated();\n    }\n\n    public function test_validation_errors()\n    {\n        $response = $this-\u003epostJson('/api/users', []);\n\n        $response-\u003eassertApiError(422)\n                 -\u003eassertApiMessage('Validation failed')\n                 -\u003eassertApiHasErrors('email');\n    }\n\n    public function test_user_data()\n    {\n        $response = $this-\u003egetJson('/api/users/1');\n\n        $response-\u003eassertApiSuccess()\n                 -\u003eassertApiDataContains(['id' =\u003e 1, 'name' =\u003e 'John Doe']);\n    }\n}\n```\n\n#### Available Test Assertions\n\n| Method | Description |\n|--------|-------------|\n| `assertApiSuccess()` | Assert response has `success: true` |\n| `assertApiError($statusCode)` | Assert response has `success: false` and optional status code |\n| `assertApiStatusCode($code)` | Assert status code in response body |\n| `assertApiMessage($message)` | Assert response message |\n| `assertApiHasData($key)` | Assert data exists (optionally check for specific key) |\n| `assertApiDataCount($count)` | Assert data array has specific count |\n| `assertApiData($expected)` | Assert data equals expected array |\n| `assertApiDataContains($expected)` | Assert data contains expected subset |\n| `assertApiPaginated()` | Assert response has pagination meta |\n| `assertApiCursorPaginated()` | Assert response has cursor pagination meta |\n| `assertApiHasErrors($key)` | Assert errors exist (optionally check for specific key) |\n\n## OpenAPI/Swagger Documentation\n\nThe package automatically generates OpenAPI 3.0 documentation from your API routes with a beautiful, modern dark-themed UI - **no additional coding required!**\n\n![Swagger UI Screenshot](docs/images/swagger-ui-screenshot.png)\n\n### Export to Multiple Formats\n\nExport your API documentation to Postman, Insomnia, JSON, or YAML with a single click.\n\n![Export Dropdown](docs/images/swagger-ui-screenshot-export.png)\n\n### Built-in Authorization\n\nEasily configure Bearer Token or API Key authentication directly from the UI.\n\n![Authorization Modal](docs/images/swagger-ui-screenshot-auth.png)\n\n### WebSocket Tester\n\nTest WebSocket connections directly from the documentation with real-time message sending and receiving.\n\n![WebSocket Tester](docs/images/swagger-ui-screenshot-websocket.png)\n\n### Zero-Configuration Auto-Generation\n\nThe package intelligently generates documentation by:\n\n- **Detecting ApiResponse method calls** - Scans your controller code for `ApiResponse::success()`, `ApiResponse::created()`, etc. and automatically determines response status codes\n- **Extracting FormRequest validation rules** (optional) - If your controller methods use FormRequest classes, validation rules are automatically converted to OpenAPI request body schemas\n- **Inferring from route patterns** - Resource controller methods (`index`, `show`, `store`, `update`, `destroy`) get meaningful summaries and descriptions\n- **Detecting pagination** - Automatically identifies paginated responses when using `-\u003epaginate()` or `-\u003ecursorPaginate()`\n\n**No FormRequest or PHP attributes required!** Just write your Laravel code normally and get instant API documentation.\n\n\u003e **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.\n\n### View Documentation\n\nSimply visit `/api-docs` in your browser to see the interactive Swagger UI:\n\n```\nhttp://your-app.com/api-docs\n```\n\n### Custom Swagger UI Features\n\nThe package includes a beautifully designed custom Swagger UI with:\n\n- **Theme Support** - Dark, Light, and Auto (system preference) themes with toggle button\n- **Custom Branding** - Display your app name and logo in the header\n- **Hero Section** - Welcome message with live API statistics (endpoints, categories, schemas)\n- **Search Bar** - Filter APIs by path, method, or description\n- **Authorization Modal** - Support for Bearer Token and API Key authentication with localStorage persistence\n- **Export Options** - Export API documentation in multiple formats (JSON, YAML, Postman, Insomnia)\n- **Responsive Design** - Works great on desktop and mobile devices\n- **Method Badges** - Color-coded HTTP method indicators (GET, POST, PUT, DELETE, PATCH)\n\n### Export API Documentation\n\nExport 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:\n\n#### OpenAPI Specification\n- **OpenAPI JSON** - Standard JSON format compatible with any OpenAPI 3.0 tool\n- **OpenAPI YAML** - Human-readable YAML format for easier editing and version control\n\n#### API Client Collections\n- **Postman Collection (v2.1)** - Ready to import into Postman with:\n  - Organized folders by API tags/categories\n  - Pre-configured base URL as collection variable\n  - Request bodies with auto-generated example data\n  - Query parameters, path variables, and headers\n\n- **Insomnia Collection (v4)** - Ready to import into Insomnia with:\n  - Workspace and environment setup\n  - Organized request groups by tags\n  - Base URL as environment variable\n  - Full request configuration\n\nAll exports are generated client-side for instant downloads with no server load.\n\n### Customization\n\nConfigure the Swagger UI appearance in your `.env` file:\n\n```env\n# App branding\nAPI_DOCS_APP_NAME=My Awesome API\nAPI_DOCS_APP_LOGO=https://example.com/logo.png\n\n# Theme color (default: #10b981 - green)\nAPI_DOCS_THEME_COLOR=#10b981\n\n# Default theme: dark, light, or auto (default: auto)\nAPI_DOCS_DEFAULT_THEME=auto\n\n# Enable/disable documentation\nAPI_DOCS_ENABLED=true\n```\n\nOr in your config file:\n\n```php\n// config/api-response.php\n\n'openapi' =\u003e [\n    'enabled' =\u003e env('API_DOCS_ENABLED', true),\n    'title' =\u003e env('API_DOCS_TITLE', 'API Documentation'),\n    'description' =\u003e 'Auto-generated API documentation',\n    'version' =\u003e '1.0.0',\n    'route_prefix' =\u003e 'api',\n    'docs_route' =\u003e 'api-docs',\n\n    // Custom branding\n    'app_name' =\u003e env('API_DOCS_APP_NAME', env('APP_NAME', 'API')),\n    'app_logo' =\u003e env('API_DOCS_APP_LOGO', null),\n    'theme_color' =\u003e env('API_DOCS_THEME_COLOR', '#10b981'),\n    'default_theme' =\u003e env('API_DOCS_DEFAULT_THEME', 'auto'), // dark, light, auto\n\n    'servers' =\u003e [\n        ['url' =\u003e env('APP_URL'), 'description' =\u003e 'API Server'],\n    ],\n],\n```\n\n### API Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api-docs` | Interactive Swagger UI |\n| `GET /api-docs/openapi.json` | Raw OpenAPI 3.0 specification |\n\n### Generate Static File\n\nGenerate a static OpenAPI JSON file:\n\n```bash\nphp artisan api:docs\n```\n\nThis creates `public/api-docs/openapi.json` that you can use with any OpenAPI-compatible tool.\n\n### Enhanced Documentation with Attributes (Optional)\n\nFor more detailed or customized documentation, you can optionally add PHP attributes to your controller methods:\n\n```php\nuse Stackmasteraliza\\ApiResponse\\Attributes\\ApiEndpoint;\nuse Stackmasteraliza\\ApiResponse\\Attributes\\ApiRequest;\nuse Stackmasteraliza\\ApiResponse\\Attributes\\ApiRequestBody;\nuse Stackmasteraliza\\ApiResponse\\Attributes\\ApiResponse;\n\nclass UserController extends Controller\n{\n    #[ApiEndpoint(\n        summary: 'List all users',\n        description: 'Retrieve a paginated list of all users in the system',\n        tags: ['Users']\n    )]\n    #[ApiRequest(name: 'page', type: 'integer', in: 'query', description: 'Page number')]\n    #[ApiRequest(name: 'per_page', type: 'integer', in: 'query', description: 'Items per page')]\n    #[ApiResponse(status: 200, description: 'Users retrieved successfully', ref: 'PaginatedResponse')]\n    public function index(): JsonResponse\n    {\n        return ApiResponse::success(User::paginate(15));\n    }\n\n    #[ApiEndpoint(\n        summary: 'Create a new user',\n        description: 'Create a new user in the system',\n        tags: ['Users']\n    )]\n    #[ApiRequestBody(\n        properties: ['name' =\u003e 'string', 'email' =\u003e 'string', 'password' =\u003e 'string'],\n        required: ['name', 'email', 'password'],\n        example: ['name' =\u003e 'John Doe', 'email' =\u003e 'john@example.com', 'password' =\u003e 'secret']\n    )]\n    #[ApiResponse(status: 201, description: 'User created successfully')]\n    #[ApiResponse(status: 422, description: 'Validation error', ref: 'ValidationErrorResponse')]\n    public function store(Request $request): JsonResponse\n    {\n        $user = User::create($request-\u003evalidated());\n        return ApiResponse::created($user);\n    }\n}\n```\n\n### Available Attributes\n\n| Attribute | Target | Description |\n|-----------|--------|-------------|\n| `#[ApiEndpoint]` | Method | Define summary, description, tags, deprecated status |\n| `#[ApiRequest]` | Method | Define query/path parameters |\n| `#[ApiRequestBody]` | Method | Define request body schema |\n| `#[ApiResponse]` | Method | Define response status, description, example |\n\n### Built-in Schema References\n\nUse these in `#[ApiResponse(ref: '...')]`:\n\n- `SuccessResponse` - Standard success response\n- `ErrorResponse` - Standard error response\n- `PaginatedResponse` - Paginated list response\n- `ValidationErrorResponse` - Validation error with field errors\n\n## Configuration\n\n```php\nreturn [\n    // Default messages\n    'default_success_message' =\u003e 'Success',\n    'default_error_message' =\u003e 'Error',\n\n    // Include debug info in error responses (when APP_DEBUG=true)\n    'include_debug_info' =\u003e env('API_RESPONSE_DEBUG', false),\n\n    // Include HTTP status code in response body\n    'include_status_code' =\u003e env('API_RESPONSE_INCLUDE_STATUS_CODE', true),\n\n    // Customize response keys\n    'keys' =\u003e [\n        'success' =\u003e 'success',\n        'message' =\u003e 'message',\n        'data' =\u003e 'data',\n        'errors' =\u003e 'errors',\n        'meta' =\u003e 'meta',\n        'status_code' =\u003e 'status_code',\n    ],\n];\n```\n\n### Disabling Status Code in Response Body\n\nIf you prefer not to include the status code in the response body, you can disable it:\n\n```env\nAPI_RESPONSE_INCLUDE_STATUS_CODE=false\n```\n\nOr in your config file:\n\n```php\n'include_status_code' =\u003e false,\n```\n\n### API Versioning\n\nThe 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.\n\n#### Enable Versioning\n\nAdd to your `.env` file:\n\n```env\nAPI_DOCS_VERSIONING=true\n```\n\nOr in your config file (`config/api-response.php`):\n\n```php\n'openapi' =\u003e [\n    // ... other options\n\n    'versioning' =\u003e [\n        'enabled' =\u003e true,\n        'auto_detect' =\u003e true,\n        'default_version' =\u003e 'v2', // Optional: set default version\n    ],\n],\n```\n\n#### Custom Version Definitions\n\nFor more control, you can define custom version patterns:\n\n```php\n'versioning' =\u003e [\n    'enabled' =\u003e true,\n    'auto_detect' =\u003e false,\n    'default_version' =\u003e 'v2',\n    'versions' =\u003e [\n        'v1' =\u003e [\n            'title' =\u003e 'API v1 (Legacy)',\n            'description' =\u003e 'Legacy API version - deprecated',\n            'pattern' =\u003e 'api/v1/*',\n        ],\n        'v2' =\u003e [\n            'title' =\u003e 'API v2 (Current)',\n            'description' =\u003e 'Current stable API version',\n            'pattern' =\u003e 'api/v2/*',\n        ],\n    ],\n],\n```\n\n#### Versioned Endpoints\n\nWhen versioning is enabled, the following endpoints become available:\n\n| Endpoint | Description |\n|----------|-------------|\n| `/api-docs` | Swagger UI with version switcher |\n| `/api-docs/openapi.json` | Full OpenAPI spec (all versions) |\n| `/api-docs/versions` | List of available versions |\n| `/api-docs/v1/openapi.json` | OpenAPI spec for v1 only |\n| `/api-docs/v2/openapi.json` | OpenAPI spec for v2 only |\n\n### WebSocket Testing\n\nThe Swagger UI includes a built-in WebSocket tester for testing real-time connections directly from the documentation.\n\n#### Features\n\n- Connect to any WebSocket endpoint\n- Send and receive messages in real-time\n- Pre-built message templates (Subscribe, Unsubscribe, Ping, Client Event)\n- Message history with timestamps\n- Connection state persistence\n\n#### Configuration\n\n```php\n'openapi' =\u003e [\n    'websocket' =\u003e [\n        'enabled' =\u003e true,\n        'url' =\u003e env('WEBSOCKET_URL', 'ws://localhost:6001'),\n        'endpoints' =\u003e [],\n    ],\n],\n```\n\nClick the **WebSocket** button in the Swagger UI header to open the tester.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackmasteraliza%2Flaravel-api-response-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackmasteraliza%2Flaravel-api-response-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackmasteraliza%2Flaravel-api-response-builder/lists"}