From daf1ffe446bf3ae4ccfeb1d0ab87043a94e74c41 Mon Sep 17 00:00:00 2001 From: "joao.patrocinio" Date: Fri, 1 Aug 2025 15:04:42 +0100 Subject: [PATCH 1/4] CakePHP 5.x compatibility --- composer.json | 2 +- config/routes.php | 6 +++--- src/Lib/SwaggerTools.php | 6 ++---- 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/composer.json b/composer.json index 8c1c0cb..fde6f20 100644 --- a/composer.json +++ b/composer.json @@ -5,7 +5,7 @@ "license": "MIT", "require": { "php": ">=7.0", - "cakephp/cakephp": "^4.0", + "cakephp/cakephp": "^5.0", "zircote/swagger-php": "^2.0" }, "require-dev": { diff --git a/config/routes.php b/config/routes.php index e92a4a7..f353c02 100644 --- a/config/routes.php +++ b/config/routes.php @@ -10,7 +10,7 @@ * - docs, defaults to /alt3/swagger/docs * - per library document, defaults to /alt3/swagger/docs/:id */ -Router::plugin('Alt3/Swagger', [ +$routes->plugin('Alt3/Swagger', [ 'path' => '/', ], function (\Cake\Routing\RouteBuilder $routes) { @@ -35,7 +35,7 @@ ); $routes->connect( - Configure::read('Swagger.docs.route') . ':id', + Configure::read('Swagger.docs.route') . '{id}', ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] ) ->setPatterns(['id' => '\w+']) @@ -47,7 +47,7 @@ ); $routes->connect( - '/alt3/swagger/docs/:id', + '/alt3/swagger/docs/{id}', ['plugin' => 'Alt3/Swagger', 'controller' => 'Docs', 'action' => 'index'] ) ->setPatterns(['id' => '\w+']) diff --git a/src/Lib/SwaggerTools.php b/src/Lib/SwaggerTools.php index a47ffba..710c748 100644 --- a/src/Lib/SwaggerTools.php +++ b/src/Lib/SwaggerTools.php @@ -4,7 +4,6 @@ namespace Alt3\Swagger\Lib; use Cake\Core\Configure; -use Cake\Filesystem\File; use Cake\Http\Exception\InternalErrorException; use Cake\Http\Exception\NotFoundException; @@ -32,9 +31,8 @@ public static function getSwaggerDocument($id, $host) if (!file_exists($filePath)) { throw new NotFoundException("Swagger json document was not found on filesystem: $filePath"); } - $fh = new File($filePath); - - return $fh->read(); + + return file_get_contents($filePath); } // otherwise crawl-generate a fresh document From 8d41fc90bd6e9f2c25d5ee46cc26fb0e62ce26c9 Mon Sep 17 00:00:00 2001 From: "joao.patrocinio" Date: Fri, 1 Aug 2025 15:36:01 +0100 Subject: [PATCH 2/4] Author rebranding --- LICENSE.txt | 2 +- README.md | 59 +++++++------------ composer.json | 10 ++-- config/routes.php | 26 ++++---- src/Controller/AppController.php | 2 +- src/Controller/DocsController.php | 6 +- src/Controller/UiController.php | 4 +- src/Lib/SwaggerTools.php | 2 +- src/Plugin.php | 4 +- src/Shell/SwaggerShell.php | 6 +- templates/Ui/index.php | 42 ++++++------- tests/App/Application.php | 4 +- .../src/Controller/DummyExcludeController.php | 2 +- .../src/Controller/DummyIncludeController.php | 2 +- .../Controller/DocsControllerTest.php | 8 +-- .../DocsCustomRouteIntegrationTest.php | 2 +- .../UiControllerCustomUiRouteTest.php | 2 +- .../UiControllerDefaultRouteTest.php | 2 +- .../TestCase/Controller/UiControllerTest.php | 8 +-- tests/TestCase/Lib/SwaggerToolsTest.php | 8 +-- tests/TestCase/Shell/SwaggerShellTest.php | 6 +- tests/bootstrap.php | 2 +- 22 files changed, 97 insertions(+), 112 deletions(-) diff --git a/LICENSE.txt b/LICENSE.txt index 52f0116..75ba3a0 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015 ALT3 B.V. +Copyright (c) 2015 CSTAF Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal 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 fde6f20..f7d1c43 100644 --- a/composer.json +++ b/composer.json @@ -1,5 +1,5 @@ { - "name": "alt3/cakephp-swagger", + "name": "cstaf/cakephp-swagger", "description": "Instant Swagger documentation for your CakePHP 4.x APIs", "type": "cakephp-plugin", "license": "MIT", @@ -12,12 +12,12 @@ "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 f353c02..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 */ -$routes->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'] + ['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 710c748..acac052 100644 --- a/src/Lib/SwaggerTools.php +++ b/src/Lib/SwaggerTools.php @@ -1,7 +1,7 @@ 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, From 7f60b5fa97089e9d76546c611521bc8c4a91f3c2 Mon Sep 17 00:00:00 2001 From: "joao.patrocinio" Date: Fri, 1 Aug 2025 15:37:29 +0100 Subject: [PATCH 3/4] Fix typo --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index f7d1c43..e53fa37 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "cstaf/cakephp-swagger", - "description": "Instant Swagger documentation for your CakePHP 4.x APIs", + "description": "Instant Swagger documentation for your CakePHP 5.x APIs", "type": "cakephp-plugin", "license": "MIT", "require": { From effd4c227f08ed967a823d8b3002dac818356b2e Mon Sep 17 00:00:00 2001 From: "joao.patrocinio" Date: Mon, 4 Aug 2025 13:08:39 +0100 Subject: [PATCH 4/4] Revert LICENSE changes --- LICENSE.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE.txt b/LICENSE.txt index 75ba3a0..52f0116 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015 CSTAF +Copyright (c) 2015 ALT3 B.V. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal