diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..cb01817 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021 Shailesh Ladumor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 7c70350..42d7cf0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,43 @@ -# laravel-swagger -This package help to setup swagger in your application easily +# Laravel Swagger + +## Installation + +Install the package by the following command, + + composer require ladumor/laravel-swagger + +## Add Provider + +Add the provider to your `config/app.php` into `provider` section if using lower version of laravel, + + Ladumor\LaravelSwagger\LaravelSwaggerServiceProvider::class, + +## Add Facade + +Add the Facade to your `config/app.php` into `aliases` section, + + 'LaravelSwagger' => \Ladumor\LaravelSwagger\LaravelSwaggerServiceProvider::class, + +## Generate Swagger file and publish the Assets. like, view + +Run the following command to publish config file, + + php artisan laravel-swagger:generate + +## Add route in `web.php` file + +``` +Route::get('/swagger-docs', function () { + return view('swagger.index'); +}); +``` + +## Other Packages + * [One Signal](https://github.com/shailesh-ladumor/one-signal) + * [Laravel PWA](https://github.com/shailesh-ladumor/laravel-pwa) (Progressive Web Application) + +## Learn Laravel Packages here +[](https://www.youtube.com/c/LaravelPackageTutorial) + +### License +The MIT License (MIT). Please see [License](LICENSE.md) File for more information diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..6f23ee7 --- /dev/null +++ b/composer.json @@ -0,0 +1,37 @@ +{ + "name": "ladumor/laravel-swagger", + "description": "this package used for the setup swagger docs for APIs.", + "type": "library", + "keywords": [ + "laravel swagger", + "swagger laravel", + "laravel", + "php" + ], + "require": { + "php": ">=5.6", + "illuminate/support": ">=5.4" + }, + "license": "MIT", + "authors": [ + { + "name": "Shailesh Ladumor", + "email": "shaileshmladumor@gmail.com" + } + ], + "autoload": { + "psr-4": { + "Ladumor\\LaravelSwagger\\": "src/" + } + }, + "extra": { + "laravel": { + "providers": [ + "Ladumor\\LaravelSwagger\\LaravelSwaggerServiceProvider" + ], + "aliases": { + "LaravelSwagger": "Ladumor\\LaravelSwagger\\LaravelSwagger" + } + } + } +} diff --git a/src/LaravelSwagger.php b/src/LaravelSwagger.php new file mode 100644 index 0000000..6da37b6 --- /dev/null +++ b/src/LaravelSwagger.php @@ -0,0 +1,18 @@ +app->singleton('laravel-swagger:generate', function ($app) { + return new GenerateSwagger(); + }); + + $this->commands([ + 'laravel-swagger:generate', + ]); + } +} diff --git a/src/commands/GenerateSwagger.php b/src/commands/GenerateSwagger.php new file mode 100644 index 0000000..6ed13b0 --- /dev/null +++ b/src/commands/GenerateSwagger.php @@ -0,0 +1,98 @@ +composer = app()['composer']; + } + + public function handle() + { + $resourceDir = resource_path('views/swagger'); + + $viewFile = file_get_contents(__DIR__ . './../../templates/index.stub'); + $swaggerTitle = $this->askTitleChangeQuestion(); + $viewFile = str_replace('$TITLE', $swaggerTitle, $viewFile); + + $this->createFile($resourceDir . DIRECTORY_SEPARATOR, 'index.blade.php', $viewFile); + $this->info('Swagger View file is published.'); + + $publicDir = public_path('swagger'); + $swaggerYamlFile = file_get_contents(__DIR__ . './../../templates/swagger.stub'); + $swaggerYamlFile = str_replace('$TITLE', $swaggerTitle, $swaggerYamlFile); + + $this->createFile($publicDir . DIRECTORY_SEPARATOR, 'swagger.yaml', $swaggerYamlFile); + $this->info('swagger.yaml file is published.'); + + $this->info('Generating autoload files!... '); + $this->composer->dumpOptimized(); + } + + private function askTitleChangeQuestion() + { + $title = 'API\'s Swagger Doc | ' . config('app.name'); + $fieldInputStr = $this->ask('The Swagger title is "' . $title . '", Are you want to change Swagger title?', 'Y/N'); + + if (strtolower($fieldInputStr) === 'y' || strtolower($fieldInputStr) === 'yes') { + $title = $this->askTitle(); + } + + return $title; + } + + /** + * Ask Swagger Docs title + * + * @return string + */ + private function askTitle() + { + $title = $this->ask('Please specify swagger doc\'s title:', ''); + if (empty($title)) { + $title = $this->askTitle(); + } + + return ucwords($title); + } + + /** + * @param $path + * @param $fileName + * @param $contents + */ + public static function createFile($path, $fileName, $contents) + { + if (!file_exists($path)) { + mkdir($path, 0755, true); + } + + $path = $path . $fileName; + + file_put_contents($path, $contents); + } +} diff --git a/templates/index.stub b/templates/index.stub new file mode 100644 index 0000000..df25005 --- /dev/null +++ b/templates/index.stub @@ -0,0 +1,17 @@ + + + $TITLE + + + +
+ + + + + diff --git a/templates/swagger.stub b/templates/swagger.stub new file mode 100644 index 0000000..cfb4fee --- /dev/null +++ b/templates/swagger.stub @@ -0,0 +1,55 @@ +swagger: '2.0' +info: + description: $TITLE APis + version: 1.0.0 + title: $TITLE +basePath: /api/ +tags: + - name: Category + description: Manage Category + +paths: + /categories: + get: + tags: + - Category + summary: Manage Category + description: 'Manage Category with this API- this is just example' + operationId: category + consumes: + - application/json + produces: + - application/json + responses: + '200': + description: successful operation + '400': + description: Bad request + post: + tags: + - Category + summary: Create Category + description: 'Create Category with this API' + operationId: createCategory + consumes: + - application/json + produces: + - application/json + parameters: + - in: query + name: name + type: string + required: true + responses: + '200': + description: successful operation + '400': + description: Bad request + security: + - api_key: [] + +securityDefinitions: + api_key: + type: apiKey + name: Authorization + in: header