diff --git a/README.md b/README.md index 1718fd0..95bff5e 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,10 @@ # cakephp-swagger -[![Build Status](https://img.shields.io/travis/alt3/cakephp-swagger/master.svg?style=flat-square)](https://travis-ci.org/alt3/cakephp-swagger) -[![StyleCI Status](https://styleci.io/repos/45741948/shield)](https://styleci.io/repos/45741948) -[![Coverage Status](https://img.shields.io/codecov/c/github/alt3/cakephp-swagger/master.svg?style=flat-square)](https://codecov.io/github/alt3/cakephp-swagger) -[![Total Downloads](https://img.shields.io/packagist/dt/alt3/cakephp-swagger.svg?style=flat-square)](https://packagist.org/packages/alt3/cakephp-swagger) -[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.txt) - -CakePHP 4.x plugin that adds auto-generated Swagger 2.0 documentation to your projects using swagger-php and swagger-ui. +CakePHP 5.x plugin that adds auto-generated Swagger 2.0 documentation to your projects using swagger-php and swagger-ui. ## Requirements -* CakePHP 4.0+ +* CakePHP 5.0+ * Some [swagger-php](https://github.com/zircote/swagger-php) annotation knowledge ## Installation @@ -18,17 +12,18 @@ CakePHP 4.x plugin that adds auto-generated Swagger 2.0 documentation to your pr Install the plugin using composer: ```bash -composer require alt3/cakephp-swagger +composer require cstaf/cakephp-swagger ``` -## Enabling +## Enabling + Enable the plugin in the `bootstrap()` method found in `src/Application.php`: ```php public function bootstrap() { parent::bootstrap(); - $this->addPlugin('Alt3/Swagger'); + $this->addPlugin('Cstaf/Swagger'); } ``` @@ -36,7 +31,7 @@ Enable the plugin in the `bootstrap()` method found in `src/Application.php`: ## Installation check -After enabling the plugin, browsing to `http://your.app/alt3/swagger` should now produce the +After enabling the plugin, browsing to `http://your.app/swagger` should now produce the [Swagger-UI](http://swagger.io/swagger-ui/) interface: ![Default UI index](/docs/images/ui-index-default.png) @@ -53,7 +48,7 @@ use Cake\Core\Configure; return [ 'Swagger' => [ 'ui' => [ - 'title' => 'ALT3 Swagger', + 'title' => 'Swagger', 'validator' => true, 'api_selector' => true, 'route' => '/swagger/', @@ -94,12 +89,10 @@ Use the `ui` section to customize the following Swagger-UI options: - `title`: sets the Swagger-UI page title, defaults to `cakephp-swagger` - `validator`: show/hide the validator image, defaults to `true` - `api_selector`: show/hide the api selector form fields, defaults to `true` -- `route`: expose the UI using a custom route, defaults to `/alt3/swagger/` -- `schemes`: array used to specify third field -[used to generate the BASE URL](https://github.com/alt3/cakephp-swagger/issues/6) -(`host` is fetched realtime, `basePath` is also fetched realtime if not -[defined via annotations](https://github.com/alt3/cakephp-swagger/issues/29)), -defaults to `null` +- `route`: expose the UI using a custom route, defaults to `/swagger/` +- `schemes`: array used to specify third field + (`host` is fetched realtime, `basePath` is also fetched realtime if not), + defaults to `null` > Please note that the UI will auto-load the first document found in the library. @@ -108,8 +101,8 @@ defaults to `null` Use the `docs` section to customize the following options: - `crawl`: enable to crawl-generate new documents instead of -serving from filesystem, defaults to `true` -- `route`: expose the documents using a custom route, defaults to `/alt3/swagger/docs/` + serving from filesystem, defaults to `true` +- `route`: expose the documents using a custom route, defaults to `/swagger/docs/` - `cors`: specify CORS headers to send with the json responses, defaults to `null` ### Library section @@ -118,16 +111,16 @@ Use the `library` section to specify one or multiple swagger documents so: - swagger-php will know which files and folders to parse for annotations - swagger-php can produce the swagger json -- this plugin can expose the json at `http://your.app/alt3/swagger/docs/:id` -(so it can be used by the UI) +- this plugin can expose the json at `http://your.app/swagger/docs/:id` + (so it can be used by the UI) The following library example would result in: - swagger-php scanning all files and folders defined in `include` - swagger-php ignoring all files and folders defined in `exclude` - two endpoints serving json swagger documents: - - `http://your.app/alt3/swagger/docs/api` - - `http://your.app/alt3/swagger/docs/editor` + - `http://your.app/swagger/docs/api` + - `http://your.app/swagger/docs/editor` ```php 'library' => [ @@ -147,7 +140,7 @@ The following library example would result in: ] ``` -It would also make `http://your.app/alt3/swagger/docs` produce a json list +It would also make `http://your.app/swagger/docs` produce a json list with links to all available documents similar to the example below. ```json @@ -156,11 +149,11 @@ with links to all available documents similar to the example below. "data": [ { "document": "api", - "link": "http://your.app/alt3/swagger/docs/api" + "link": "http://your.app/swagger/docs/api" }, { "document": "editor", - "link": "http://your.app/alt3/swagger/docs/editor" + "link": "http://your.app/swagger/docs/editor" } ] } @@ -178,7 +171,7 @@ bin/cake swagger makedocs ``` > The host argument (e.g. your.app.com) is required, should not include -protocols and is used to set the `host` property inside your swagger documents. +> protocols and is used to set the `host` property inside your swagger documents. ## Quickstart Annotation Example @@ -261,11 +254,3 @@ Which should result in: - [The Swagger Specification](https://github.com/swagger-api/swagger-spec) - [PHP Annotation Examples](https://github.com/zircote/swagger-php/tree/master/Examples) - [Swagger Document Checklist](http://apievangelist.com/2015/06/15/my-minimum-viable-definition-for-a-complete-swagger-api-definition/) - -## Contribute - -Before submitting a PR make sure: - -- [PHPUnit](http://book.cakephp.org/4.0/en/development/testing.html#running-tests) -and [CakePHP Code Sniffer](https://github.com/cakephp/cakephp-codesniffer) tests pass -- [Coveralls Code Coverage ](https://coveralls.io/github/alt3/cakephp-swagger) remains at 100% diff --git a/composer.json b/composer.json index 8c1c0cb..e53fa37 100644 --- a/composer.json +++ b/composer.json @@ -1,23 +1,23 @@ { - "name": "alt3/cakephp-swagger", - "description": "Instant Swagger documentation for your CakePHP 4.x APIs", + "name": "cstaf/cakephp-swagger", + "description": "Instant Swagger documentation for your CakePHP 5.x APIs", "type": "cakephp-plugin", "license": "MIT", "require": { "php": ">=7.0", - "cakephp/cakephp": "^4.0", + "cakephp/cakephp": "^5.0", "zircote/swagger-php": "^2.0" }, "require-dev": { "phpunit/phpunit": "^7.0" }, "support": { - "issues": "https://github.com/alt3/cakephp-swagger/issues", - "source": "https://github.com/alt3/cakephp-swagger" + "issues": "https://github.com/joaopatrocinio/cakephp-swagger/issues", + "source": "https://github.com/joaopatrocinio/cakephp-swagger" }, "autoload": { "psr-4": { - "Alt3\\Swagger\\": "src" + "Cstaf\\Swagger\\": "src" }, "files": [ "aliases.php" @@ -25,7 +25,7 @@ }, "autoload-dev": { "psr-4": { - "Alt3\\Swagger\\Test\\": "tests" + "Cstaf\\Swagger\\Test\\": "tests" } } } diff --git a/config/routes.php b/config/routes.php index e92a4a7..2abe7ff 100644 --- a/config/routes.php +++ b/config/routes.php @@ -6,11 +6,11 @@ /* * Connect routes using configuration file, otherwise use defaults: * - * - UI, defaults to /alt3/swagger - * - docs, defaults to /alt3/swagger/docs - * - per library document, defaults to /alt3/swagger/docs/:id + * - UI, defaults to /swagger + * - docs, defaults to /swagger/docs + * - per library document, defaults to /swagger/docs/:id */ -Router::plugin('Alt3/Swagger', [ +$routes->plugin('Cstaf/Swagger', [ 'path' => '/', ], function (\Cake\Routing\RouteBuilder $routes) { @@ -18,12 +18,12 @@ if (Configure::read('Swagger.ui.route')) { $routes->connect( Configure::read('Swagger.ui.route'), - ['plugin' => 'Alt3/Swagger', 'controller' => 'Ui', 'action' => 'index'] + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Ui', 'action' => 'index'] ); } else { $routes->connect( - '/alt3/swagger/', - ['plugin' => 'Alt3/Swagger', 'controller' => 'Ui', 'action' => 'index'] + '/cstaf/swagger/', + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Ui', 'action' => 'index'] ); } @@ -31,24 +31,24 @@ if (Configure::read('Swagger.docs.route')) { $routes->connect( Configure::read('Swagger.docs.route'), - ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index'] ); $routes->connect( - Configure::read('Swagger.docs.route') . ':id', - ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] + Configure::read('Swagger.docs.route') . '{id}', + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index'] ) ->setPatterns(['id' => '\w+']) ->setPass(['id']); } else { $routes->connect( - '/alt3/swagger/docs', - ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] + '/cstaf/swagger/docs', + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index'] ); $routes->connect( - '/alt3/swagger/docs/:id', - ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] + '/cstaf/swagger/docs/{id}', + ['plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index'] ) ->setPatterns(['id' => '\w+']) ->setPass(['id']); diff --git a/src/Controller/AppController.php b/src/Controller/AppController.php index 4031990..b213cc4 100644 --- a/src/Controller/AppController.php +++ b/src/Controller/AppController.php @@ -1,7 +1,7 @@ $document, 'link' => Router::url([ - 'plugin' => 'Alt3/Swagger', + 'plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index', $document, diff --git a/src/Controller/UiController.php b/src/Controller/UiController.php index ee11aaa..b714328 100644 --- a/src/Controller/UiController.php +++ b/src/Controller/UiController.php @@ -1,7 +1,7 @@ config['library']); return Router::url([ - 'plugin' => 'Alt3/Swagger', + 'plugin' => 'Cstaf/Swagger', 'controller' => 'Docs', 'action' => 'index', $defaultDocument, diff --git a/src/Lib/SwaggerTools.php b/src/Lib/SwaggerTools.php index a47ffba..acac052 100644 --- a/src/Lib/SwaggerTools.php +++ b/src/Lib/SwaggerTools.php @@ -1,10 +1,9 @@ read(); + + return file_get_contents($filePath); } // otherwise crawl-generate a fresh document diff --git a/src/Plugin.php b/src/Plugin.php index 5b8ac40..aa5a189 100644 --- a/src/Plugin.php +++ b/src/Plugin.php @@ -1,13 +1,13 @@ Html->meta([ - 'link' => $this->Url->assetUrl('Alt3/Swagger./images/favicon-32x32.png', ['fullBase' => true]), + 'link' => $this->Url->assetUrl('Cstaf/Swagger./images/favicon-32x32.png', ['fullBase' => true]), 'rel' => 'icon', 'sizes' => '32x32', 'type' => 'image/png', ]); echo $this->Html->meta([ - 'link' => $this->Url->assetUrl('Alt3/Swagger./images/favicon-16x16.png', ['fullBase' => true]), + 'link' => $this->Url->assetUrl('Cstaf/Swagger./images/favicon-16x16.png', ['fullBase' => true]), 'rel' => 'icon', 'sizes' => '16x16', 'type' => 'image/png' @@ -39,33 +39,33 @@ // screen stylesheets echo $this->Html->css([ - 'Alt3/Swagger.typography.css', - 'Alt3/Swagger.reset.css', - 'Alt3/Swagger.screen.css', + 'Cstaf/Swagger.typography.css', + 'Cstaf/Swagger.reset.css', + 'Cstaf/Swagger.screen.css', ], ['media' => 'screen', 'once' => false, 'fullBase' => true]); // print stylesheet echo $this->Html->css([ - 'Alt3/Swagger.reset.css', - 'Alt3/Swagger.print.css', + 'Cstaf/Swagger.reset.css', + 'Cstaf/Swagger.print.css', ], ['media' => 'print', 'once' => false, 'fullBase' => true]); // javascript libraries echo $this->Html->script([ - 'Alt3/Swagger./lib/object-assign-pollyfill.js', - 'Alt3/Swagger./lib/jquery-1.8.0.min.js', - 'Alt3/Swagger./lib/jquery.slideto.min.js', - 'Alt3/Swagger./lib/jquery.wiggle.min.js', - 'Alt3/Swagger./lib/jquery.ba-bbq.min.js', - 'Alt3/Swagger./lib/handlebars-4.0.5.js', - 'Alt3/Swagger./lib/lodash.min.js', - 'Alt3/Swagger./lib/backbone-min.js', - 'Alt3/Swagger./swagger-ui.js', - 'Alt3/Swagger./lib/highlight.9.1.0.pack.js', - 'Alt3/Swagger./lib/highlight.9.1.0.pack_extended.js', - 'Alt3/Swagger./lib/jsoneditor.min.js', - 'Alt3/Swagger./lib/marked.js', - 'Alt3/Swagger./lib/swagger-oauth.js' + 'Cstaf/Swagger./lib/object-assign-pollyfill.js', + 'Cstaf/Swagger./lib/jquery-1.8.0.min.js', + 'Cstaf/Swagger./lib/jquery.slideto.min.js', + 'Cstaf/Swagger./lib/jquery.wiggle.min.js', + 'Cstaf/Swagger./lib/jquery.ba-bbq.min.js', + 'Cstaf/Swagger./lib/handlebars-4.0.5.js', + 'Cstaf/Swagger./lib/lodash.min.js', + 'Cstaf/Swagger./lib/backbone-min.js', + 'Cstaf/Swagger./swagger-ui.js', + 'Cstaf/Swagger./lib/highlight.9.1.0.pack.js', + 'Cstaf/Swagger./lib/highlight.9.1.0.pack_extended.js', + 'Cstaf/Swagger./lib/jsoneditor.min.js', + 'Cstaf/Swagger./lib/marked.js', + 'Cstaf/Swagger./lib/swagger-oauth.js' ], ['fullBase' => true]); ?> diff --git a/tests/App/Application.php b/tests/App/Application.php index c78fc13..ba88e34 100644 --- a/tests/App/Application.php +++ b/tests/App/Application.php @@ -1,9 +1,9 @@ 'Alt3\Swagger\Test\App', + 'namespace' => 'Cstaf\Swagger\Test\App', 'encoding' => 'UTF-8', 'base' => false, 'baseUrl' => false,