{"id":22888227,"url":"https://github.com/kentaroutakeda/laravel-openapi-validator","last_synced_at":"2026-01-24T06:55:57.797Z","repository":{"id":214585569,"uuid":"736867606","full_name":"KentarouTakeda/laravel-openapi-validator","owner":"KentarouTakeda","description":"Request and response validators based on the OpenAPI Specification.","archived":false,"fork":false,"pushed_at":"2025-03-09T00:14:32.000Z","size":242,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-01T23:06:30.250Z","etag":null,"topics":["api","docs","documentation","laravel","middleware","openapi","rest","specification","swagger","validation","validator"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/kentaroutakeda/laravel-openapi-validator","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/KentarouTakeda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-29T05:33:55.000Z","updated_at":"2025-03-09T00:13:05.000Z","dependencies_parsed_at":"2024-02-04T12:55:54.464Z","dependency_job_id":"f17ba76d-15f3-4196-8ad2-8e16237712ca","html_url":"https://github.com/KentarouTakeda/laravel-openapi-validator","commit_stats":{"total_commits":152,"total_committers":1,"mean_commits":152.0,"dds":0.0,"last_synced_commit":"6c37049b46dd6ae77454ebbc1bdaf1061f4e31a5"},"previous_names":["kentaroutakeda/laravel-openapi-validator"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KentarouTakeda%2Flaravel-openapi-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KentarouTakeda%2Flaravel-openapi-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KentarouTakeda%2Flaravel-openapi-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KentarouTakeda%2Flaravel-openapi-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KentarouTakeda","download_url":"https://codeload.github.com/KentarouTakeda/laravel-openapi-validator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873936,"owners_count":21817708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","docs","documentation","laravel","middleware","openapi","rest","specification","swagger","validation","validator"],"created_at":"2024-12-13T20:47:26.344Z","updated_at":"2026-01-24T06:55:57.792Z","avatar_url":"https://github.com/KentarouTakeda.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel OpenAPI Validator\n\nRequest and response validators based on the OpenAPI Specification.\n\n## Summary\n\n* Validate any request and response with a pre-prepared OpenAPI Spec.\n* Automatically load specs from [Laravel OpenAPI](https://nova-edge.github.io/laravel-openapi/) or [L5 Swagger](https://github.com/DarkaOnLine/L5-Swagger/wiki).\n* You can also load your own specs without using these libraries.\n* You can customize validation and error logging behavior on a per-route or application-wide basis.\n* Can display [Swagger UI](https://swagger.io/tools/swagger-ui/). You can view the documentation and test the API.\n\n\n## Requirements\n\n* PHP 8.1 or higher\n* Laravel 10.0 or higher\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require kentaroutakeda/laravel-openapi-validator\n```\n\n## Usage\n\n1. Configure OpenAPI Specification\n\n   If you're using Laravel OpenAPI, you don't need to do anything.\n\n   For L5 Swagger, the following settings are required:\n\n   ```ini\n   # .env\n   OPENAPI_VALIDATOR_PROVIDER=\"l5-swagger\"\n   ```\n\n   How to load your own schema without using these packages will be\n   explained later.\n\n2. Register Middleware\n\n   ```php\n   Route::get('/example', ExampleController::class)\n       -\u003emiddleware(OpenApiValidator::class); // \u003c- Add this line\n   ```\n\n   Routes with this setting will be validated for all requests including\n   Feature Tests, and depending on the settings, responses as well.\n\n   *NOTE:*  \n   This repository's [./e2e](./e2e) directory contains working examples\n   for e2e testing. You can see middleware configuration examples in\n   Routing, and actual validations and failures in Tests.\n\n3. (Optional) Customize Middleware\n\n   If necessary, you can change Middleware behavior for each route.\n\n   ```php\n   Route::get('/', ExampleController::class)\n       -\u003emiddleware(OpenApiValidator::config(\n           provider: 'admin-api', // \u003c- Use spec other than default\n           skipResponseValidation: true // \u003c- Skip Response Validation\n       ));\n   ```\n\n   *NOTE:*  \n   Response validation for large amounts of data can take a long time.\n   It would be a good idea to switch on/off validation depending on the\n   route and `APP_*` environment variables.\n\n4. Deployment\n\n   When deploying your application to production, you should make sure\n   that you run the `openapi-validator:cache` Artisan command\n   during your deployment process:\n\n   ```bash\n   php artisan openapi-validator:cache\n   ```\n\n   This command caches the OpenAPI Spec defined in your application.\n   If you change the definition for development, you need to\n   clear it as follows:\n\n   ```bash\n   php artisan openapi-validator:clear\n   ```\n\n   Alternatively, these commands are automatically executed when running\n   Laravel's built-in optimization commands:\n\n   ```bash\n   php artisan optimize        # Includes openapi-validator:cache\n   php artisan optimize:clear  # Includes openapi-validator:clear\n   ```\n\n## (Optional) Swagger UI support\n\nYou can view the Swagger UI just by installing the package. No additional\nconfiguration is required.\n\n1. Install package.\n\n   ```bash\n   composer require --dev swagger-api/swagger-ui\n   ```\n\n2. Display `APP_URL/openapi-validator/documents` in browser.\n\n   ```bash\n   open http://localhost:8000/openapi-validator/documents\n   ```\n\n*NOTE:*  \nBy default, the Swagger UI can only be displayed when `APP_DEBUG` is enabled.\n\n## (Optional) Customization\n\n### Publish Configuration\n\nYou can publish the config file to change behavior.\n\n```bash\nphp artisan openapi-validator:publish\n```\n\nAlternatively, most settings can be changed using environment variables.\nCheck the comments in [config/openapi-validator.php](config/openapi-validator.php) for details.\n\n### Your own schema providers\n\n1. If you want to use your own schema providers, first publish the config.\n\n2. Next, implement a class to retrieve the schema.\n\n   ```php\n   class MyResolver implements ResolverInterface\n   {\n       public function getJson(array $options): string\n       {\n           // This example assumes that the schema exists in the root directory.\n           return File::get(base_path('openapi.json'));\n       }\n   }\n   ```\n\n3. Finally, set it in your config.\n\n   ```php\n   return [\n       // Set the provider name.\n       'default' =\u003e 'my-resolver',\n\n       'providers' =\u003e [\n           // Set the provider name you created.\n           'my-resolver' =\u003e [\n               // Specify the class you created in the `resolver` parameter.\n               'resolver' =\u003e MyResolver::class,\n           ],\n       ],\n   ];\n   ```\n\n### Error responses and customization\n\nBy default, it is formatted according to\n[RFC 7807 - Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc7807).\n\nValidation errors, stack traces and original response\ncan also be included depending on your settings.\nFor example, it might look like this:\n\n```json\n{\n  \"title\": \"NoResponseCode\",\n  \"detail\": \"OpenAPI spec contains no such operation [/,get,201]\", // Error reason\n  \"status\": 500, // Same as HTTP response code\n  \"originalResponse\": { \"status\": \"201\" }, // Original response before validation\n  \"trace\": [\n    { \"error\": \"...\", \"message\": \"...\", \"file\": \"...\", \"line\": 42 },\n    { \"...\": \"...\" }\n  ]\n}\n```\n\nHere's how to change to a different format:\n\n1. First, implement a class to generate a response. For example:\n\n   ```php\n   class MyErrorRenderer implements ErrorRendererInterface\n   {\n       public function render(\n           \\Throwable $error,\n           Request $request,\n           ?Response $response = null,\n       ): Response {\n           return new Response(\n               match ($response === null) {\n                   ErrorType::Request =\u003e \"Request Error: \" . $error-\u003egetMessage(),\n                   ErrorType::Response =\u003e \"Response Error: \" . $error-\u003egetMessage(),\n               }\n           );\n       }\n   }\n   ```\n\n2. Next, register the class to the service container.\n\n   ```php\n   // AppServiceProvider.php\n\n   public function register(): void\n   {\n       $this-\u003eapp-\u003ebind(\n           ErrorRendererInterface::class,\n           MyErrorRenderer::class\n       );\n   }\n   ```\n\n### Events\n\nIf a validation error occurs, an event will be fired\ndepending on the type of error.\n\n* `ValidationFailedInterface` - All errors\n  * `RequestValidationFailed` - Request validation error\n  * `ResponseValidationFailed` - Response validation error\n\n## Contributing and Development\n\nFeel free to open an Issue or add a Pull request.\n\nWhen adding a pull request, please refer to the following setup steps.\n\n```bash\n# Clone this repository and move to the directory.\ngit clone https://github.com/KentarouTakeda/laravel-openapi-validator.git\ncd laravel-openapi-validator\n\n# Install dependencies.\ncomposer install\n\n# (Optional) Install tools: The commit hook automatically formats the code.\nnpm install\n\n# Run tests.\nvendor/bin/phpunit\n```\n\n## License\n\nLaravel OpenAPI Validator is open-sourced software licensed under the\n[MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentaroutakeda%2Flaravel-openapi-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentaroutakeda%2Flaravel-openapi-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentaroutakeda%2Flaravel-openapi-validator/lists"}