{"id":13684495,"url":"https://github.com/alt3/cakephp-swagger","last_synced_at":"2025-09-02T01:33:19.053Z","repository":{"id":2115848,"uuid":"45741948","full_name":"alt3/cakephp-swagger","owner":"alt3","description":"Swagger plugin for documenting your CakePHP APIs","archived":false,"fork":false,"pushed_at":"2022-05-11T12:11:31.000Z","size":2568,"stargazers_count":64,"open_issues_count":8,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-25T23:29:11.882Z","etag":null,"topics":["cakephp","php","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/alt3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-07T15:29:59.000Z","updated_at":"2024-02-15T20:46:18.000Z","dependencies_parsed_at":"2022-08-08T22:30:12.681Z","dependency_job_id":null,"html_url":"https://github.com/alt3/cakephp-swagger","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/alt3/cakephp-swagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alt3%2Fcakephp-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alt3%2Fcakephp-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alt3%2Fcakephp-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alt3%2Fcakephp-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alt3","download_url":"https://codeload.github.com/alt3/cakephp-swagger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alt3%2Fcakephp-swagger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273218428,"owners_count":25065913,"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","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cakephp","php","swagger","swagger-ui"],"created_at":"2024-08-02T14:00:34.144Z","updated_at":"2025-09-02T01:33:19.026Z","avatar_url":"https://github.com/alt3.png","language":"JavaScript","readme":"# cakephp-swagger\n\n[![Build Status](https://img.shields.io/travis/alt3/cakephp-swagger/master.svg?style=flat-square)](https://travis-ci.org/alt3/cakephp-swagger)\n[![StyleCI Status](https://styleci.io/repos/45741948/shield)](https://styleci.io/repos/45741948)\n[![Coverage Status](https://img.shields.io/codecov/c/github/alt3/cakephp-swagger/master.svg?style=flat-square)](https://codecov.io/github/alt3/cakephp-swagger)\n[![Total Downloads](https://img.shields.io/packagist/dt/alt3/cakephp-swagger.svg?style=flat-square)](https://packagist.org/packages/alt3/cakephp-swagger)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.txt)\n\nCakePHP 4.x plugin that adds auto-generated Swagger 2.0 documentation to your projects using swagger-php and swagger-ui.\n\n## Requirements\n\n* CakePHP 4.0+\n* Some [swagger-php](https://github.com/zircote/swagger-php) annotation knowledge\n\n## Installation\n\nInstall the plugin using composer:\n\n```bash\ncomposer require alt3/cakephp-swagger\n```\n\n## Enabling \nEnable the plugin in the `bootstrap()` method found in `src/Application.php`:\n\n```php\n    public function bootstrap()\n    {\n        parent::bootstrap();\n        $this-\u003eaddPlugin('Alt3/Swagger');\n    }\n```\n\n\u003e Also make sure that AssetMiddleware is loaded inside `Application.php` or all Swagger page assets will 404.\n\n## Installation check\n\nAfter enabling the plugin, browsing to `http://your.app/alt3/swagger` should now produce the\n[Swagger-UI](http://swagger.io/swagger-ui/) interface:\n\n![Default UI index](/docs/images/ui-index-default.png)\n\n## Configuration\n\nAll configuration for this plugin is done through the `/config/swagger.php`\nconfiguration file. TLDR full example below.\n\n```php\n\u003c?php\nuse Cake\\Core\\Configure;\n\nreturn [\n    'Swagger' =\u003e [\n        'ui' =\u003e [\n            'title' =\u003e 'ALT3 Swagger',\n            'validator' =\u003e true,\n            'api_selector' =\u003e true,\n            'route' =\u003e '/swagger/',\n            'schemes' =\u003e ['http', 'https']\n        ],\n        'docs' =\u003e [\n            'crawl' =\u003e Configure::read('debug'),\n            'route' =\u003e '/swagger/docs/',\n            'cors' =\u003e [\n                'Access-Control-Allow-Origin' =\u003e '*',\n                'Access-Control-Allow-Methods' =\u003e 'GET, POST',\n                'Access-Control-Allow-Headers' =\u003e 'X-Requested-With'\n            ]\n        ],\n        'library' =\u003e [\n            'api' =\u003e [\n                'include' =\u003e ROOT . DS . 'src',\n                'exclude' =\u003e [\n                    '/Editor/'\n                ]\n            ],\n            'editor' =\u003e [\n                'include' =\u003e [\n                    ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',\n                    ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',\n                    ROOT . DS . 'src' . DS . 'Model'\n                ]\n            ]\n        ]\n    ]\n];\n```\n\n### UI section\n\nUse the `ui` section to customize the following Swagger-UI options:\n\n- `title`: sets the Swagger-UI page title, defaults to `cakephp-swagger`\n- `validator`: show/hide the validator image, defaults to `true`\n- `api_selector`: show/hide the api selector form fields, defaults to `true`\n- `route`: expose the UI using a custom route, defaults to `/alt3/swagger/`\n- `schemes`: array used to specify third field\n[used to generate the BASE URL](https://github.com/alt3/cakephp-swagger/issues/6)\n(`host` is fetched realtime, `basePath` is also fetched realtime if not\n[defined via annotations](https://github.com/alt3/cakephp-swagger/issues/29)),\ndefaults to `null`\n\n\u003e Please note that the UI will auto-load the first document found in the library.\n\n### Docs section\n\nUse the `docs` section to customize the following options:\n\n- `crawl`: enable to crawl-generate new documents instead of\nserving from filesystem, defaults to `true`\n- `route`: expose the documents using a custom route, defaults to `/alt3/swagger/docs/`\n- `cors`: specify CORS headers to send with the json responses, defaults to `null`\n\n### Library section\n\nUse the `library` section to specify one or multiple swagger documents so:\n\n- swagger-php will know which files and folders to parse for annotations\n- swagger-php can produce the swagger json\n- this plugin can expose the json at `http://your.app/alt3/swagger/docs/:id`\n(so it can be used by the UI)\n\nThe following library example would result in:\n\n- swagger-php scanning all files and folders defined in `include`\n- swagger-php ignoring all files and folders defined in `exclude`\n- two endpoints serving json swagger documents:\n    - `http://your.app/alt3/swagger/docs/api`\n    - `http://your.app/alt3/swagger/docs/editor`\n\n```php\n'library' =\u003e [\n    'api' =\u003e [\n        'include' =\u003e ROOT . DS . 'src',\n        'exclude' =\u003e [\n            '/Editor/'\n        ]\n    ],\n    'editor' =\u003e [\n        'include' =\u003e [\n            ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',\n            ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',\n            ROOT . DS . 'src' . DS . 'Model'\n        ]\n    ]\n]\n```\n\nIt would also make `http://your.app/alt3/swagger/docs` produce a json list\nwith links to all available documents similar to the example below.\n\n```json\n{\n    \"success\": true,\n    \"data\": [\n        {\n            \"document\": \"api\",\n            \"link\": \"http://your.app/alt3/swagger/docs/api\"\n        },\n        {\n            \"document\": \"editor\",\n            \"link\": \"http://your.app/alt3/swagger/docs/editor\"\n        }\n    ]\n}\n```\n\n## SwaggerShell\n\nThis plugin comes with a shell that should simplify deployment in production\nenvironments. Simply run the following command to create `cakephp_swagger`\nprefixed filesystem documents in `tmp/cache` for all entities found in your\nlibrary.\n\n```bash\nbin/cake swagger makedocs \u003chost\u003e\n```\n\n\u003e The host argument (e.g. your.app.com) is required, should not include\nprotocols and is used to set the `host` property inside your swagger documents.\n\n## Quickstart Annotation Example\n\nExplaining [swagger-php](https://github.com/zircote/swagger-php)\nannotation voodoo is beyond this plugin but to give yourself a head start while\ncreating your first library document you might want to copy/paste the following\nworking example into any of your php files.\n\n\u003e **Note**: the weird non-starred syntax ensures\n\u003e compatibility with the CakePHP Code Sniffer.\n\n```php\n\u003c?php\n/**\n    @SWG\\Swagger(\n        @SWG\\Info(\n            title=\"cakephp-swagger\",\n            description=\"Quickstart annotation example\",\n            termsOfService=\"http://swagger.io/terms/\",\n            version=\"1.0.0\"\n        )\n    )\n\n    @SWG\\Get(\n        path=\"/cocktails\",\n        summary=\"Retrieve a list of cocktails\",\n        tags={\"cocktail\"},\n        consumes={\"application/json\"},\n        produces={\"application/json\"},\n        @SWG\\Parameter(\n            name=\"sort\",\n            description=\"Sort results by field\",\n            in=\"query\",\n            required=false,\n            type=\"string\",\n            enum={\"name\", \"description\"}\n        ),\n        @SWG\\Response(\n            response=\"200\",\n            description=\"Successful operation\",\n            @SWG\\Schema(\n                type=\"object\",\n                ref=\"#/definitions/Cocktail\"\n            )\n        ),\n        @SWG\\Response(\n            response=429,\n            description=\"Rate Limit Exceeded\"\n        )\n    )\n\n    @SWG\\Definition(\n        definition=\"Cocktail\",\n        required={\"name\", \"description\"},\n        @SWG\\Property(\n            property=\"id\",\n            type=\"integer\",\n            description=\"CakePHP record id\"\n        ),\n        @SWG\\Property(\n            property=\"name\",\n            type=\"string\",\n            description=\"CakePHP name field\"\n        ),\n        @SWG\\Property(\n            property=\"description\",\n            type=\"string\",\n            description=\"Description of a most tasty cocktail\"\n        )\n    )\n*/\n```\n\nWhich should result in:\n\n![UI Quickstart Example](/docs/images/ui-quickstart-example.png)\n\n## Additional Reading\n\n- [The Swagger Specification](https://github.com/swagger-api/swagger-spec)\n- [PHP Annotation Examples](https://github.com/zircote/swagger-php/tree/master/Examples)\n- [Swagger Document Checklist](http://apievangelist.com/2015/06/15/my-minimum-viable-definition-for-a-complete-swagger-api-definition/)\n\n## Contribute\n\nBefore submitting a PR make sure:\n\n- [PHPUnit](http://book.cakephp.org/4.0/en/development/testing.html#running-tests)\nand [CakePHP Code Sniffer](https://github.com/cakephp/cakephp-codesniffer) tests pass\n- [Coveralls Code Coverage ](https://coveralls.io/github/alt3/cakephp-swagger) remains at 100%\n","funding_links":[],"categories":["REST and API"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falt3%2Fcakephp-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falt3%2Fcakephp-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falt3%2Fcakephp-swagger/lists"}