{"id":13684519,"url":"https://github.com/cnizzardini/cakephp-swagger-bake","last_synced_at":"2025-04-12T15:38:24.561Z","repository":{"id":38040622,"uuid":"254755946","full_name":"cnizzardini/cakephp-swagger-bake","owner":"cnizzardini","description":"Automatically generate OpenAPI, Swagger, and Redoc documentation from your existing CakePHP code.","archived":false,"fork":false,"pushed_at":"2025-04-11T02:09:45.000Z","size":8994,"stargazers_count":60,"open_issues_count":6,"forks_count":23,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-11T03:06:55.486Z","etag":null,"topics":["cake-plugin","cakephp","cakephp-api","cakephp-plugin","cakephp4","openapi","redoc","swagger-bake","swagger-documentation","swagger-ui"],"latest_commit_sha":null,"homepage":"http://cakephpswaggerbake.cnizz.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/cnizzardini.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"publiccode":null,"codemeta":null}},"created_at":"2020-04-10T23:27:29.000Z","updated_at":"2025-04-11T02:08:32.000Z","dependencies_parsed_at":"2024-01-22T07:48:01.455Z","dependency_job_id":"45d22e9f-ffa8-49b0-b28f-ea274420558c","html_url":"https://github.com/cnizzardini/cakephp-swagger-bake","commit_stats":{"total_commits":782,"total_committers":13,"mean_commits":60.15384615384615,"dds":"0.021739130434782594","last_synced_commit":"42c70bff80d99f422242a3f6d8dd47f8c34f5269"},"previous_names":[],"tags_count":103,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cnizzardini%2Fcakephp-swagger-bake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cnizzardini%2Fcakephp-swagger-bake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cnizzardini%2Fcakephp-swagger-bake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cnizzardini%2Fcakephp-swagger-bake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cnizzardini","download_url":"https://codeload.github.com/cnizzardini/cakephp-swagger-bake/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590591,"owners_count":21129855,"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":["cake-plugin","cakephp","cakephp-api","cakephp-plugin","cakephp4","openapi","redoc","swagger-bake","swagger-documentation","swagger-ui"],"created_at":"2024-08-02T14:00:34.414Z","updated_at":"2025-04-12T15:38:24.536Z","avatar_url":"https://github.com/cnizzardini.png","language":"PHP","readme":"# Swagger Bake\n#### A delightfully tasty plugin for generating OpenAPI, Swagger and Redoc\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/cnizzardini/cakephp-swagger-bake.svg?style=flat-square)](https://packagist.org/packages/cnizzardini/cakephp-swagger-bake)\n[![Build](https://github.com/cnizzardini/cakephp-swagger-bake/actions/workflows/push.yml/badge.svg)](https://github.com/cnizzardini/cakephp-swagger-bake/actions/workflows/push.yml)\n[![Coverage Status](https://coveralls.io/repos/github/cnizzardini/cakephp-swagger-bake/badge.svg?branch=master)](https://coveralls.io/github/cnizzardini/cakephp-swagger-bake?branch=master)\n[![MixerApi](https://img.shields.io/badge/mixer-api-red?logo=data:image/png;base64,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)](http://mixerapi.com)\n[![CakePHP](https://img.shields.io/badge/cakephp-^5-red?logo=cakephp)](https://book.cakephp.org/5/en/index.html)\n[![Minimum PHP Version](https://img.shields.io/badge/php-^8.1-8892BF.svg?logo=php)](https://php.net/)\n[![OpenAPI](https://img.shields.io/badge/openapi-3.0-green?logo=openapi-initiative)](https://www.openapis.org/)\n\nAutomatically generate OpenApi, Swagger, and Redoc documentation from your existing CakePHP code\n\n- Creates OpenApi paths and operations from your [RESTful](https://book.cakephp.org/5/en/development/rest.html) routes \nand controllers.\n- Creates OpenAPI Schema from your Entities and Tables.\n- Integrates with: \n[Paginator](https://book.cakephp.org/5/en/controllers/components/pagination.html), \n[friendsofcake/search](https://github.com/FriendsOfCake/search), \n[Validator](https://api.cakephp.org/5.0/class-Cake.Validation.Validator.html), and \n[Bake](#bake-theme).\n- Provides additional functionality through Attributes and Doc Blocks.\n\nThe current release is for CakePHP 5 and PHP 8.1, see previous releases for older versions of CakePHP and PHP.\n\n| Version | Branch                                                                    | Cake Version | PHP Version | \n|---------|---------------------------------------------------------------------------|--------------|-------------|\n| 3.*     | master                                                                    | ^5.0         | ^8.1        |\n| 2.*     | [2.x](https://github.com/cnizzardini/cakephp-swagger-bake/tree/2.x)       | ^4.2         | ^8.0        |\n| 1.*     | [1.next](https://github.com/cnizzardini/cakephp-swagger-bake/tree/1.next) | ^4.0         | ^7.2        | \n\nCheck out the demo applications for examples.\n\n| Demos                                                           | Source                                                               | \n|-----------------------------------------------------------------|----------------------------------------------------------------------|\n| [Swagger Bake v3 demo](http://cakephpswaggerbake.cnizz.com/)    | https://github.com/cnizzardini/cakephp-swagger-bake-demo             |\n| [MixerAPI + Swagger Bake demo (v3)](https://demo.mixerapi.com/) | https://github.com/mixerapi/demo                                     | \n| v2 demo                                                         | https://github.com/cnizzardini/cakephp-swagger-bake-demo/tree/2.next |\n| v1 demo                                                         | https://github.com/cnizzardini/cakephp-swagger-bake-demo/tree/1.next |\n\n\n## Table of Contents\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [Attributes](#attributes)\n- [Events](#event-system)\n- [Customizing Exception Responses](#customizing-exception-response-samples)\n- [Extending Views and Controllers](#extending-views-and-controllers)\n- [Multiple Instances of SwaggerBake](#multiple-instances-of-swagger-bake)\n- [Debug Commands](#debug-commands)\n- [Bake Theme](#bake-theme)\n- [Common Issues](#common-issues)\n- [Contributing](#contribute)\n\n## Installation\n\nYou can install via the [composer](https://getcomposer.org/) dependency manager:\n\n```console\ncomposer require cnizzardini/cakephp-swagger-bake\n```\n\nNext load the plugin via `bin/cake plugin load SwaggerBake` or if you prefer manually: \n\n```php\n# src/Application.php\npublic function bootstrap(): void\n{\n    // other logic...\n    $this-\u003eaddPlugin('SwaggerBake');\n}\n```\n\nFor standard applications that have not split their API into plugins, the automated setup is the easiest. Otherwise, \nskip to the manual setup. \n\n### Automated Setup\n\nUse the `swagger install` command and then [add a route](#add-route).\n\n```console\nbin/cake swagger install\n```\n\n### Manual Setup\n\n- Create a base [swagger.yml](assets/swagger.yml) file at `config\\swagger.yml`. An example file is provided \n[here](assets/swagger.yml). \n\n- Create a [swagger_bake.php](assets/swagger_bake.php) config file at `config/swagger_bake.php` file. See the example \nfile [here](assets/swagger_bake.php) for further explanation. Then just [add a route](#add-route).\n\nFor more read sections on [Multiple Instances of SwaggerBake](#multiple-instances-of-swagger-bake) \nand [Extending Views and Controllers](#extending-views-and-controllers)\n\n### Add Route\n\nCreate a route for the SwaggerUI page in `config/routes.php`, example:\n\n```php\n$builder-\u003econnect(\n    '/api', # this will be the \"homepage\" for your Swagger or Redoc UI\n    ['plugin' =\u003e 'SwaggerBake', 'controller' =\u003e 'Swagger', 'action' =\u003e 'index']\n);\n``` \n\nYou can now browse to either `/api` for swagger or `/api?doctype=redoc` for redoc. Your OpenAPI JSON\nwill exist at `/api/swagger.json`.\n\n## Getting Started\n\n- You can generate OpenAPI json from the command line at anytime by running the `swagger bake` command: \n\n```console\nbin/cake swagger bake\n```\n\n- If Hot Reload is enabled ([see config](assets/swagger_bake.php)) OpenAPI will be generated each time you browse \nto SwaggerUI (or Redoc) in your web browser.\n\n- You can also generate OpenAPI programmatically: \n\n```php\n$swagger = (new \\SwaggerBake\\Lib\\SwaggerFactory())-\u003ecreate()-\u003ebuild();\n$swagger-\u003egetArray(); # returns swagger array\n$swagger-\u003etoString(); # returns swagger json\n$swagger-\u003ewriteFile('/full/path/to/your/swagger.json'); # writes swagger.json\n```\n\n- Checkout the [debug commands](#debug-commands) for troubleshooting and the [bake theme](#bake-theme) for generating \nRESTful controllers.\n\n### Routes\n\nYour [RESTful routes](https://book.cakephp.org/5/en/development/routing.html#restful-routing) are used to build \nOpenAPI paths and operations.\n\n### Controllers\n\nSwaggerBake will parse the [DocBlocks](https://docs.phpdoc.org/latest/guides/docblocks.html) on your controller \nactions for additional OpenAPI data.\n\n```php\n/**\n * OpenAPI Operation Summary\n * \n * This displays as the operations long description\n * \n * @link https://book.cakephp.org/5/en/index.html External documentation\n * @deprecated Indicates the operation is deprecated\n * @throws \\Cake\\Http\\Exception\\BadRequestException Appears as 400 response with this description\n * @throws \\Exception Appears as 500 response with this description\n */\npublic function index() {}\n```\n\nIf you prefer, you may use the [OpenApiOperation](docs/attributes.md#OpenApiOperation), \n[OpenApiResponse](docs/attributes.md#OpenApiResponse) attributes instead. These attributes take precedence over doc \nblock parsing. Read below for a full list of attributes.\n\n### Models\n\nOpenAPI schema is built from your Table and Entity classes and any validators you've defined in them. You may adjust\nthe default schema using the [OpenApiSchema](docs/attributes.md#OpenApiSchema) and\n[OpenApiSchemaProperty](docs/attributes.md#OpenApiSchemaProperty) attributes.\n\n## Attributes\n\nFor additional functionality the following [PHP8 Attributes](https://www.php.net/manual/en/language.attributes.overview.php) \nmay be used. These can be imported individually from the `SwaggerBake\\Lib\\Attribute` namespace. \n[Read the Attributes docs](docs/attributes.md) for detailed examples. If you are using \n[version 1](https://github.com/cnizzardini/cakephp-swagger-bake/tree/1.next) you will need to use annotations.\n\n\n| Attribute                                                             | Usage              | Description                                                                                                        | \n|-----------------------------------------------------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------|\n| [OpenApiDto](docs/attributes.md#OpenApiDto)                           | Controller Action  | Builds OpenAPI query params and request bodies from Data Transfer Objects                                          |\n| [OpenApiForm](docs/attributes.md#OpenApiForm)                         | Controller Action  | Builds OpenAPI for application/x-www-form-urlencoded request bodies                                                |\n| [OpenApiHeader](docs/attributes.md#OpenApiHeader)                     | Controller Action  | Create OpenAPI header parameters                                                                                   |\n| [OpenApiOperation](docs/attributes.md#OpenApiOperation)               | Controller Action  | Modifies OpenAPI operation                                                                                         |\n| [OpenApiPaginator](docs/attributes.md#OpenApiPaginator)               | Controller Action  | Create OpenAPI query params from CakePHP Paginator Component                                                       |\n| [OpenApiPath](docs/attributes.md#OpenApiPath)                         | Controller         | Modifies OpenAPI paths                                                                                             |\n| [OpenApiPathParam](docs/attributes.md#OpenApiPathParam)               | Controller Action  | Modify an existing OpenAPI path parameter                                                                          |\n| [OpenApiQueryParam](docs/attributes.md#OpenApiQueryParam)             | Controller Action  | Builds OpenAPI query param                                                                                         |\n| [OpenApiRequestBody](docs/attributes.md#OpenApiRequestBody)           | Controller Action  | Modify OpenAPI request body                                                                                        |\n| [OpenApiResponse](docs/attributes.md#OpenApiResponse)                 | Controller Action  | Modify OpenAPI response                                                                                            |\n| [OpenApiSchema](docs/attributes.md#OpenApiSchema)                     | Entity             | Modifies OpenAPI schema                                                                                            |\n| [OpenApiSchemaProperty](docs/attributes.md#OpenApiSchemaProperty)     | Entity or Class    | Modifies an OpenAPI schema property or defines OpenApiResponse schema                                              |\n| [OpenApiSearch](docs/attributes.md#OpenApiSearch)                     | Controller Action  | Create OpenAPI query params from CakePHP Search plugin                                                             |\n| [OpenApiSecurity](docs/attributes.md#OpenApiSecurity)                 | Controller Action  | Create/modify OpenAPI security                                                                                     |\n\n## Event System\n\nSwaggerBake comes with an [event system](docs/events.md) to allow for further control over your OpenAPI schema.\n\n| Event                                                             | Description                                                 | \n|-------------------------------------------------------------------|-------------------------------------------------------------|\n| [SwaggerBake.Operation.created](docs/events.md#operation-created) | Dispatched each time an OpenAPI Path \u003e Operation is created |\n| [SwaggerBake.Path.created](docs/events.md#path-created)           | Dispatched each time an OpenAPI Path is created             |\n| [SwaggerBake.Schema.created](docs/events.md#schema-created)       | Dispatched each time an OpenAPI Schema is created           |\n| [SwaggerBake.initialize](docs/events.md#initialize)               | Dispatched during initialization phase on SwaggerBake       |\n| [SwaggerBake.beforeRender](docs/events.md#before-render)          | Dispatched before SwaggerBake outputs OpenAPI JSON          |\n\n## Customizing Exception Response Samples\n\nBy default, SwaggerBake uses `'#/components/schemas/Exception'` as your OpenAPI documentations Exception schema. See the \ndefault [swagger.yml](assets/swagger.yml) and `exceptionSchema` in [swagger_bake.php](assets/swagger_bake.php) for more \ninfo. You can further customize with attributes and `@throws`.\n\n### OpenApiResponse\n\nUsing the `ref` or `schema` properties of [OpenApiResponse](docs/attributes.md#OpenApiResponse).\n\n### Using the `@throws` tag and OpenApiExceptionSchemaInterface\n\nImplement `SwaggerBake\\Lib\\OpenApiExceptionSchemaInterface` on your exception class, then document \nthe exception with a `@throws` tag in your controller action's doc block.\n\n```php\n/**\n * @throws \\App\\Exception\\MyException\n */\npublic function add(){}\n```\n\nExample exception class:\n\n```php\nclass MyException implements OpenApiExceptionSchemaInterface \n{\n    public static function getExceptionCode(): string\n    {\n        return '400';\n    }\n\n    public static function getExceptionDescription(): ?string\n    {\n        return 'An optional description'; // returning null omits the response description\n    }\n\n    public static function getExceptionSchema(): Schema|string\n    {\n        return (new \\SwaggerBake\\Lib\\OpenApi\\Schema())  \n            -\u003esetTitle('MyException')\n            -\u003esetProperties([\n                (new SchemaProperty())-\u003esetType('string')-\u003esetName('code')-\u003esetExample('400'),\n                (new SchemaProperty())-\u003esetType('string')-\u003esetName('message')-\u003esetExample('error'),\n                (new SchemaProperty())-\u003esetType('string')-\u003esetName('wherever')-\u003esetExample('whatever you want')\n            ]);\n    }\n}\n```\n\n## Extending Views and Controllers\n\nIt's possible to write extensions for SwaggerBake. Read the [extension documentation](docs/extensions.md). There are \nseveral other options to extend functionality documented below:\n\n#### Using Your Own SwaggerUI\n\nYou may use your own swagger or redoc install in lieu of the version that comes with SwaggerBake. Simply don't add a custom \nroute as indicated in the installation steps. In this case just reference the generated swagger.json within your \nuserland Swagger UI install.\n\n#### Using Your Own Controller\n\nYou might want to perform some additional logic (checking for authentication) before rendering the built-in Swagger UI. \nThis is easy to do. Just create your own route and controller, then reference the built-in layout and template: \n\n```php\n// config/routes.php\n$builder-\u003econnect(\n    '/my-swagger-docs', \n    ['controller' =\u003e 'MySwagger', 'action' =\u003e 'index']\n);\n```\n\nTo get started, copy [SwaggerController](src/Controller/SwaggerController.php) into your project.\n\n#### Using Your Own Layout and Templates\n\nYou will need to use your own controller (see above). From there you can copy the [layouts](templates/layout) and \n[templates](templates/Swagger) into your project and inform your controller action to use them instead. Checkout out \nthe CakePHP documentation on [Views](https://book.cakephp.org/5/en/views.html) for specifics. This can be useful if \nyou'd like to add additional functionality to SwaggerUI (or Redoc) using their APIs or if your project is not \ninstalled in your web servers document root (i.e. a sub-folder).\n\n## Multiple Instances of Swagger Bake\n\nIf your application has multiple APIs that are split into plugins you can generate unique OpenAPI schema, Swagger UI, \nand Redoc for each plugin. Setup a new `swagger_bake.php` and `swagger.yaml` in `plugins/OtherApi/config`. These \nconfigurations should point to your plugins paths and namespaces. Next, create a custom \n[SwaggerController](src/Controller/SwaggerController.php) and load the configuration within `initialize()`:\n\n```php\n    public function initialize(): void\n    {\n        parent::initialize();\n        Configure::load('OtherApi.swagger_bake', 'default', false); // note: `false` for the third argument is important         \n    }\n```\n\nWhen running `bin/cake swagger bake` you will need to specify your plugins swagger_bake config:\n\n```console\nbin/cake swagger bake --config OtherApi.swagger_bake\n```\n\n## Debug Commands\n\nIn addition to `swagger bake` these console helpers provide insight into how your Swagger documentation is generated.\n\n#### `swagger routes` \nDisplays a list of routes that can be viewed in Swagger.\n\n```sh\nbin/cake swagger routes\n```\n\n#### `swagger models` \nDisplays a list of models that can be viewed in Swagger.\n\n```sh\nbin/cake swagger models\n```\n\n## Bake Theme\n\nSwaggerBake comes with [Bake templates](templates/bake) for scaffolding RESTful controllers compatible with SwaggerBake \nand OpenAPI 3.0 schema. Using the bake theme is completely optional, but will save you some time since the default \nbake theme is not specifically designed for RESTful APIs.\n\n```\nbin/cake bake controller {Name} --theme SwaggerBake\n```\n\n## Common Issues\n\n### Swagger UI \n\n`No API definition provided.`\n\nVerify that swagger.json exists.\n\n### SwaggerBakeRunTimeExceptions \n\n`Unable to create swagger file. Try creating an empty file first or checking permissions`\n\nCreate the swagger.json manually matching the path in your `config/swagger_bake.php` file.\n\n`Output file is not writable`\n\nChange permissions on your `swagger.json file`, `764` should do.\n\n`Controller not found`\n\nMake sure a controller actually exists for the route resource.\n\n### Missing routes\n\nMake sure yours route are properly defined in `config/routes.php` per the \n[CakePHP RESTful routing](https://book.cakephp.org/5/en/development/routing.html#restful-routing) documentation.\n\n### Missing request or response samples\n\nSample schema is determined using [CakePHP naming conventions](https://book.cakephp.org/5/en/intro/conventions.html). \nDoes your controller name match your model names? For customizing response schema see \n[OpenApiResponse](docs/attributes.md#OpenApiResponse).\n\n### Missing request schema\n\nSample schema is determined using [CakePHP naming conventions](https://book.cakephp.org/5/en/intro/conventions.html).\nDoes your controller name match your model names? For customizing request schema see \n[OpenApiRequestBody](docs/attributes.md#OpenApiRequestBody).\n\n### Missing CSRF token body\n\nEither disable CSRF protection on your main route in `config/routes.php` or enable CSRF protection in Swagger \nUI. The library does not currently support adding this in for you.\n\n### HTTP DELETE issues with Swagger UI\n\nSwagger UI sends HTTP DELETE without an `accept` header. If the record does not exist, an exception is generated. \nThis results in an HTML response being generated which can be quite large and cause the UI to be slow to render. To \nget around this you can force an `accept` value on the header using the CakePHP middleware:\n\n```php\n# src/Application.php\n\npublic function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue\n{\n\t$middlewareQueue\n\t    -\u003eadd(function(ServerRequestInterface $request, RequestHandlerInterface $handler){\n\t        $accept = $request-\u003egetHeader('accept');\n\t        if ($request-\u003egetMethod() === 'DELETE' \u0026\u0026 reset($accept) === '*/*') {\n\t            $request = $request-\u003ewithHeader('accept', 'application/json');\n\t        }\n\n\t        return $handler-\u003ehandle($request);\n\t    });\n\n\t// other middleware...\n\t\n\treturn $middlewareQueue;\n}\n```\n\nRead more about [CakePHP middleware](https://book.cakephp.org/5/en/controllers/middleware.html) in the official \ndocumentation.\n\n## Contribute\n\nSend pull requests to help improve this library. You can include SwaggerBake in your primary Cake project as a \nlocal source to make developing easier:\n\n- Make a fork of this repository and clone it to your localhost\n\n- Remove `cnizzardini\\cakephp-swagger-bake` from your `composer.json`\n\n- Add a paths repository to your `composer.json`\n\n```\n\"minimum-stability\": \"dev\",\n\"repositories\": [\n    {\n        \"type\": \"path\",\n        \"url\": \"/absolute/local-path-to/cakephp-swagger-bake\",\n        \"options\": {\n          \"symlink\": true\n        }\n    }\n]\n```\n\n- Run `composer require cnizzardini/cakephp-swagger-bake @dev`\n\nUndo these steps when you're done. Read the full composer documentation on loading from path here: \n[https://getcomposer.org/doc/05-repositories.md#path](https://getcomposer.org/doc/05-repositories.md#path)\n\nCheck out the [extensions](docs/extensions.md) documentation to add functionality to this project.\n\n### Tests + Analysis\n\nPHPUnit Test Suite:\n\n```console\ncomposer test\n```\n\nPHPUnit, PHPCS, PHPSTAN, and PHPMD:\n\n```console\ncomposer analyze\n```\n\n[GrumPHP](https://github.com/phpro/grumphp) can be used to run tests and static analyzers in a pre-commit hook.\n\n```console\ncomposer grumphp-init\n```\n\nI've set grumphp to be installed globally: https://github.com/phpro/grumphp/blob/master/doc/installation/global.md\n","funding_links":[],"categories":["REST and API"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcnizzardini%2Fcakephp-swagger-bake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcnizzardini%2Fcakephp-swagger-bake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcnizzardini%2Fcakephp-swagger-bake/lists"}