{"id":20173555,"url":"https://github.com/ronasit/laravel-swagger","last_synced_at":"2025-04-04T16:14:21.037Z","repository":{"id":21875703,"uuid":"94301390","full_name":"RonasIT/laravel-swagger","owner":"RonasIT","description":"Laravel-Swagger is a fully automate tool which allows to generate and save swagger-based documentation after successful completing your application's feature tests.","archived":false,"fork":false,"pushed_at":"2023-12-26T03:42:47.000Z","size":5032,"stargazers_count":128,"open_issues_count":7,"forks_count":42,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T08:28:37.783Z","etag":null,"topics":["automation","laravel","openapi","php","swagger","swagger-documentation"],"latest_commit_sha":null,"homepage":"https://ronasit.com","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/RonasIT.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2017-06-14T07:16:31.000Z","updated_at":"2024-04-17T07:27:08.162Z","dependencies_parsed_at":"2023-09-25T00:35:26.478Z","dependency_job_id":"66d68703-b313-45ad-8a16-6e3a674e41bb","html_url":"https://github.com/RonasIT/laravel-swagger","commit_stats":{"total_commits":286,"total_committers":20,"mean_commits":14.3,"dds":0.7587412587412588,"last_synced_commit":"1acfdaa8bf1f355530eca48515337cb0dd38193c"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Flaravel-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Flaravel-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Flaravel-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Flaravel-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RonasIT","download_url":"https://codeload.github.com/RonasIT/laravel-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208145,"owners_count":20901570,"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":["automation","laravel","openapi","php","swagger","swagger-documentation"],"created_at":"2024-11-14T01:36:37.789Z","updated_at":"2025-04-04T16:14:21.017Z","avatar_url":"https://github.com/RonasIT.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"resources/assets/images/hero.svg\" \u003e\n\n# Laravel Swagger plugin\n\n\u003cp align=\"left\"\u003e\n\u003ca href=\"https://packagist.org/packages/ronasit/laravel-swagger\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/ronasit/laravel-swagger\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ronasit/laravel-swagger\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ronasit/laravel-swagger\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ronasit/laravel-swagger\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/ronasit/laravel-swagger\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[![Laravel Swagger](https://github.com/RonasIT/laravel-swagger/actions/workflows/laravel.yml/badge.svg?branch=master)](https://github.com/RonasIT/laravel-swagger/actions/workflows/laravel.yml)\n[![Coverage Status](https://coveralls.io/repos/github/RonasIT/laravel-swagger/badge.svg?branch=master)](https://coveralls.io/github/RonasIT/laravel-swagger?branch=master)\n\n## Comparison to another documentation generators\n\n|                                                    | LaravelSwagger         | [Scramble](https://github.com/dedoc/scramble) |\n|----------------------------------------------------|------------------------|----------------------------------------------|\n| Force developers to write tests                    | :white_check_mark:     | :x:                                          |\n| Guarantee that API works                           | :white_check_mark:     | :x:                                          |\n| Works with any route types covered by tests        | :white_check_mark:     | :x:                                          |\n| Generate response schema using JSON Resource class | :x: | :white_check_mark:                             |\n| Runtime documentation generation                   | :x:                    | :white_check_mark:                        |\n\n## Introduction\n\nThis plugin is designed to generate documentation for your REST API during the \npassing PHPUnit tests.\n\n## Installation\n\n1. Install the package using the following command: `composer require ronasit/laravel-swagger`\n\n\u003e ***Note***\n\u003e \n\u003e For Laravel 5.5 or later the package will be auto-discovered.\n\u003e For older versions add the `AutoDocServiceProvider` to the\n\u003e providers array in `config/app.php` as follow:\n\u003e \n\u003e ```php\n\u003e 'providers' =\u003e [\n\u003e     ...\n\u003e     RonasIT\\AutoDoc\\AutoDocServiceProvider::class,\n\u003e ],\n\u003e ```\n\n2. Run `php artisan vendor:publish --provider=RonasIT\\\\AutoDoc\\\\AutoDocServiceProvider`\n1. Add `\\RonasIT\\AutoDoc\\Http\\Middleware\\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\\app.php`:\n\n```php\n    return Application::configure(basePath: dirname(__DIR__))\n        -\u003ewithMiddleware(function (Middleware $middleware) {\n            $middleware-\u003euse([\n                ...\n                \\RonasIT\\AutoDoc\\Http\\Middleware\\AutoDocMiddleware::class,\n            ]);\n        });\n```\n\n4. Add `\\RonasIT\\AutoDoc\\Traits\\AutoDocTestCaseTrait` trait to `tests/TestCase.php`\n1. Configure documentation saving using one of the next ways:\n  - Add `SwaggerExtension` to the `\u003cextensions\u003e` block of your `phpunit.xml`.\n  **Please note that this way will be removed after updating**\n  **PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)**\n\n  ```xml\n  \u003cphpunit\u003e\n      \u003cextensions\u003e\n          \u003cbootstrap class=\"RonasIT\\AutoDoc\\Support\\PHPUnit\\Extensions\\SwaggerExtension\"/\u003e\n      \u003c/extensions\u003e\n      \u003ctestsuites\u003e\n          \u003ctestsuite name=\"Feature\"\u003e\n              \u003cdirectory suffix=\"Test.php\"\u003e./tests/Feature\u003c/directory\u003e\n          \u003c/testsuite\u003e\n      \u003c/testsuites\u003e\n  \u003c/phpunit\u003e\n  ```\n  - Call `php artisan swagger:push-documentation` console command after\n    the `tests` stage in your CI/CD configuration\n\n## Usage\n\n### Basic usage\n\n1. Create request class:\n\n    ```php\n    \u003c?php\n\n    namespace App\\Http\\Requests;  \n    \n    use Illuminate\\Foundation\\Http\\FormRequest;\n    \n    /**\n    * @summary Update user\n    *\n    * @deprecated \n    *\n    * @description\n    * This request should be used for updating the user data\n    *\n    * @_204 Successful\n    * \n    * @is_active will indicate whether the user is active or not\n    */\n    class UpdateUserDataRequest extends FormRequest\n    {\n        /**\n         * Determine if the user is authorized to make this request.\n         *\n         * @return bool\n         */\n        public function authorize()\n        {\n            return true;\n        }  \n    \n        /**\n         * Validation Rules\n         *\n         * @return array\n         */\n        public function rules()\n        {\n            return [\n                'name' =\u003e 'string',\n                'is_active' =\u003e 'boolean',\n                'age' =\u003e 'integer|nullable'\n            ];\n        }\n    }\n\n    ```\n    \u003e ***Note***\n    \u003e \n    \u003e For correct working of plugin you'll have to dispose all the validation rules \n    \u003e in the `rules()` method of your request class. Also, your request class\n    \u003e must be connected to the controller via [dependency injection](https://laravel.com/docs/11.x/container#introduction).\n    \u003e Plugin will take validation rules from the request class and generate fields description\n    \u003e of input parameter.\n\n2. Create a controller and a method for your route:\n\n    ```php\n    \u003c?php\n\n    namespace App\\Http\\Controllers;\n\n    use App\\Http\\Requests\\Users\\UpdateUserDataRequest;\n\n    class UserController extends Controller\n    {\n        public function update(UpdateUserDataRequest $request, UserService $service, $id)\n        {\n            // do something here...\n\n            return response('', Response::HTTP_NO_CONTENT);\n        }\n    }\n    ```\n\n    \u003e ***Note***\n    \u003e \n    \u003e Dependency injection of request class is optional but if it not presents,\n    \u003e the \"Parameters\" block in the API documentation will be empty.\n\n3. Create test for API endpoint:\n\n    ```php\n    public function testUpdate()\n    {\n        $response = $this-\u003ejson('put', '/users/1', [\n            'name': 'Updated User',\n            'is_active': true,\n            'age': 22\n        ]);\n\n        $response-\u003eassertStatus(Response::HTTP_NO_CONTENT);\n    }\n    ```\n\n4. Run tests\n5. Go to route defined in the `auto-doc.route` config\n6. Profit!\n\n    ![img.png](resources/assets/images/img.png)\n\n### Annotations\n\nYou can use the following annotations in your request classes to customize documentation of your API endpoints:\n\n- **@summary** - short description of request\n- **@description** - implementation notes\n- **@_204** - custom description of response code. You can specify any code as you want.\n- **@some_field** - description of the field from the rules method\n- **@deprecated** - mark route as deprecated\n \n\u003e ***Note***\n\u003e \n\u003e If you do not use request class, the summary and description and parameters will be empty.\n\n### Configs\n\n- `auto-doc.route` - route for generated documentation\n- `auto-doc.basePath` - root of your API\n\n### Custom driver\n\nYou can specify the way to collect and view documentation by creating your own custom driver.\n\nYou can find example of drivers [here](https://github.com/RonasIT/laravel-swagger/tree/master/src/Drivers).\n\n### Viewing OpenAPI documentation\n\nAs of version 2.2, the package includes the ability to switch between OpenAPI documentation\nviewers. To access different viewers, modify the `documentation_viewer` configuration.\nThis change is reflected immediately, without the need to rebuild the documentation file.\n\n### Merging additional documentations\n\nThe package supports the integration of the primary documentation with additional valid\nOpenAPI files specified in the `additional_paths` configuration.\n\n## Migration guides\n\n[3.0.1-beta](MIGRATION-GUIDES.md#301-beta)\n\n## Contributing\n\nThank you for considering contributing to Laravel Swagger plugin! The contribution guide\ncan be found in the [Contributing guide](CONTRIBUTING.md).\n\n## License\n\nLaravel Swagger plugin is open-sourced software licensed under the [MIT license](LICENSE).\n \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronasit%2Flaravel-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronasit%2Flaravel-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronasit%2Flaravel-swagger/lists"}