PHPackages cnizzardini/cakephp-swagger-bake - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. cnizzardini/cakephp-swagger-bake ActiveCakephp-plugin[API Development](/categories/api) cnizzardini/cakephp-swagger-bake ================================ Automatically generate OpenApi, Swagger, and Redoc documentation from your existing cakephp project v3.3.5(3mo ago)60171.2k—3.8%24[1 issues](https://github.com/cnizzardini/cakephp-swagger-bake/issues)2MITPHPPHP ^8.1CI passing Since Apr 15Pushed 3mo ago6 watchersCompare [ Source](https://github.com/cnizzardini/cakephp-swagger-bake)[ Packagist](https://packagist.org/packages/cnizzardini/cakephp-swagger-bake)[ RSS](/packages/cnizzardini-cakephp-swagger-bake/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (13)Versions (116)Used By (2) Swagger Bake ============ [](#swagger-bake) #### A delightfully tasty plugin for generating OpenAPI, Swagger and Redoc [](#a-delightfully-tasty-plugin-for-generating-openapi-swagger-and-redoc) [![Latest Version on Packagist](https://camo.githubusercontent.com/d0cab92e0e2273dbd0723a389674a3d732236ff64ea8d236ae75e500d244b9a9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636e697a7a617264696e692f63616b657068702d737761676765722d62616b652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cnizzardini/cakephp-swagger-bake)[![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)[![Coverage Status](https://camo.githubusercontent.com/02784651f0fea48d45c1c835034809e67f318b296af55132b7bf3fdf6a8aaaa7/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f636e697a7a617264696e692f63616b657068702d737761676765722d62616b652f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/cnizzardini/cakephp-swagger-bake?branch=master)[![MixerApi](https://camo.githubusercontent.com/d467ff75477d185c9ee8ee3bc8251b0fcd2ff0a4296b9d6e650ed90194931a78/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d697865722d6170692d7265643f6c6f676f3d646174613a696d6167652f706e673b6261736536342c6956424f5277304b47676f414141414e5355684555674141414241414141414f434159414141416d4c35794b4141414679487055574852535958636763484a765a6d6c735a5342306558426c494756346157594141486a6172566470736a4d6e44507a504b5849456b42444c63566972636f4d635038317165393737746c51383973437769466133454750562f766d3771372f774952323073754b4469383570664779306b524971516139506e48656a37627a7642333071482b314b7439314261474b557642353932754d543275553134617868386d653743727548776a5a6b7275483534624879714e64336b47696e315737734e6851334968654466346561743647794230346f2b3263767246574d5a2f5852344d465346537a455249304e6139794a4e774a65763452666d4866434f4d4d5764574a574b495150456844793464356c567238543945487971616b6e2b3466374a2f6d553967682b634f6d4f6175373744694f5064723772302f7643664248525a30654c783952586b6e75766f6665327645765767564733493271536259345a444d79676e4f63306838766a4a366a37655556635153646449486e565257646378555244554b557259303031795854545a6c6c4d4155524c6a54784b6f6b493832774a37696c52343659544c6450496375554a42346b4a4e4d614f5a4c68597a3134317a765749435671344751386e416d4d4755483137715a35312f63716e657936444944444c6234677134614d513159417a6c7868326a49496a70577a655a424a397279362f66416775684367566c30687a67594e4a356d63686958724846553266474f45473574704252766d34446f4168724338415968674c614752626a6a505a4533686a7747434251416e4a6953786b4b4742477141456d57325a4879464769736a546e657a4c456b35476730497a644243474848487470455468444c576b48386542735151306c597249673438524b5552456d4f6e5858696e504e754a4c6e6b32567376336e6e766734382b425134325348444268784269534a45694977644b644e484845474e4d6956544351676d324573596e7447544b6e473257374c4c504963656343734b6e32434c464656394369535656716c79524a717172766f5961613270474e57534b5a7073303133774c4c62625545577564752b335358666339394e6a54565732722b7558364139584d566f326d556d4f637636716856586c2f544a6952546d526f4273584947696a7568774949614271613657437370614863304578485a444d57416b675a32716871686d4b5130445a443073335637715863622b6d6d4a507957627651723564535137763951546b4736723770396f316f643531795a697131644f446a566a4e32482f6861536f6f415258554a4368584c4a7342414d7a55647762675666624a342b4b7a6a4c347536436f724f6d54366d654455537a45733067645a71424e306867773659305a4d415967387746744834766b53473161626e4f4f54346d587876477a31556a5a79334c76446c7a6f652f736d374b73685542495444617274616f3931737547726e647050532b334d464f41356452647148754e324f625538546153676d2b754844354f365946752b654e4e39325854684178765856386443546175652b6f3766332b6a4e4759617377466e6478724956436f464f6e584b53375a7175584e344b6f4444596f354f485164503153473635586a56335334584d3759494e31304f71546f7578356a6a43676a5179476e31706d4358323969364e78777570577058374b454f77626759734e6871502f4b725a624e6c64723546497454567838432b7a4a46316977466a442f563062506a6c56634a476133336836565a336350546b7739516445514458446a674f76784a42586254567677556c387642534f395a77775a79777858484e545262366e4c4558425a7970485452305974746934786150643638314a335a4f787a30786d2f2b4b4c626e3645574a494d474d6e714d47304f3274697065554d3376472b52494262374851716b4b4d3857565461533332746a73484c556b322b6c4c6a6e496e2f51735766546161716e6159366169454c626e666c366b553479695057694e664a417939585451616c4731495230417658455638734c5334754d62566a6a4a745969695643375246412b70726d7046452f596572373764652f513177376d34324d346c5a545034464c3337726668356f34753870457064306939664c474c684979546f4a564e766930396a50656a6234472b343677584a7a397733726a334a617546454b683632706b784752427276784c374c6a2f704c662f4e684f706b553833355a424b4854494b543737427842704135492b6c3031584b6a545430484e536b3766703276764649723370416831356f646b56757a3747305178766c6c353935534f4f7844666e424b6270306b63667872322f6b326a68644957646b6d6c655a783748396b49495670664f62375a794934457374744f55344259586f6835486b6362596870515253387050766e6b644c71717457435059715465543455524173437a70315575366a6c3970572f4237776262504563664f597453366d646a564a2f34772f787459354275334e6d516944654f4841334b45504c793739716d384c667751334f4950525964672f4f6c564c624b33635a366a394b344d57754931754b4267694e502b327642504a4e756b2f766b69636244352f6e2f4648685035365164776d2f504d587273616136476b734a315a31414552347642386531554335464865394b2b4d2b752f67556c35745939586d61314e7741414159527051304e5153554e444948427962325a706247554141436952665a4539534d4e41484d5666553656464b6f495745584549574a307369496f346168574b55434855437130366d467a36425530616b68515852384731344f44485974584278566c58423164424550774163584a30556e535245762b5846467245656e44636a336633486e6676414b4657597072564d51356f756d306d347a45786e566b5641363849516b41762b6a45734d3875596b365145326f3676652f6a346568666c576533502f546d3631617a46414a3949504d734d30796265494a37657441334f2b38526856704256346e50694d5a4d7553507a496463586a4e3835356c77576547545a5479586e694d4c47596232476c68566e423149696e69434f71706c4f2b6b505a5935627a4657537456574f4f652f495768724c36797a4857615134686a4555755149454a424255575559434e4b7130364b68535474783972344231322f524336465845557763697967444132793677662f67392f6457726e4a4353387046414d3658787a6e5977514937414c3171754e38487a744f2f51547750774e5865744e667267457a6e3652586d31726b434f6a5a426936756d35717942317a7541414e50686d7a4b7275536e4b6552797750735a66564d47364c734675746138336872374f48304155745256346759344f4152473835533933756264776462652f6a3354364f3848506d42796b684977667a674141414147596b74485241442f415038412f36433970354d414141414a6345685a6377414143784d4141417354415143616e4267414141414864456c4e5251666b43414953467a6435354362354141414368456c455156516f7a3357535430685555525447762f7675665450767a646a595047634d47386b732f307a61474b4d354334654a6773786174416769534163715774516d69494a414637724b467259714368707930557044616d4f356951774a676a5254694277545377332f6f4f576f54546250392b613932364c356f3058663676416476682f6e33487349414c77747137354e54504d36414169794247495273566d4541346132306374553759702f636e526d532b2f6c7765414a2b2b70366e354179424c734e726b4d6843465972534d726a414e592b6a534d784d546b4d773477454a6b636a6151443775664c4459796343744b70794942575a6e5a76475078494a53476c524459392b666741674378434e354d6947774242726141414941546850546f3139784e3479377765413636596f426a49517a6b644f50627459765a6e4c584b4955426566746e6f3637545742304f777a7a6c7766497866502b4964506c4a41735877686b4170304c3533344f6c31385337773864727a4c6e46462b44632b713232717564395a63553953716c65332f5630522f78494d41774178764a7931357579306b564b6159356847457474725331526c6759594330732b77726b54414f794b6f69754b4d696a4c63717a76394d6c6d52584565694d5657664158374b3850755a4c4a666b7152566d3833572f72447a6b562f496a434b796b757971334c52617262445a62464e7472533052747a746641674348777746465557596b53664b6f7172716961567074426d416b4e697253745253642b4771614a674473546c6d6c466f736c33563754646431782f6c7a54467744494143686a6f557739752b425656625758633537582f66694a58394d3069474c6d7542594a49634d4151436c3155774159394e625747495a2b565569397153425a643270316752744c3858696a4c4d7475516b69464c4d74676a455542614954673174483659336141694177416b735273424d2f2b69544e593579727575424f494e31384c7a382f5064786357466f4a534367414a7a6e6d6b3865795a6147716147546267395265746d38626c5850496e4c5a555577313551674c563839303376774f752b73564151484c6955436953714f6e754774747a42717a322b61566b51696f5473536678587a4a55487569336e753257584a375376382f343441507747337950673336563370377741414141415355564f524b35435949493d)](http://mixerapi.com)[![CakePHP](https://camo.githubusercontent.com/0ca1a72496462cc4391b788843557f6b4fbd722c00cfaf7a1fbe0f5dc0a1300a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f63616b657068702d253545352d7265643f6c6f676f3d63616b65706870)](https://book.cakephp.org/5/en/index.html)[![Minimum PHP Version](https://camo.githubusercontent.com/88f5af675e16072d2bae3a481dc6e9f8297bbce952642cc0fbb1e0825b36963e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d3838393242462e7376673f6c6f676f3d706870)](https://php.net/)[![OpenAPI](https://camo.githubusercontent.com/4fb8e6689f5a4b384f1939ddc1ac4dbaeb4e8472d33b27a65fa7906bf29a85a6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6f70656e6170692d332e302d677265656e3f6c6f676f3d6f70656e6170692d696e6974696174697665)](https://www.openapis.org/) Automatically generate OpenApi, Swagger, and Redoc documentation from your existing CakePHP code - Creates OpenApi paths and operations from your [RESTful](https://book.cakephp.org/5/en/development/rest.html) routes and controllers. - Creates OpenAPI Schema from your Entities and Tables. - Integrates with: [Paginator](https://book.cakephp.org/5/en/controllers/components/pagination.html), [friendsofcake/search](https://github.com/FriendsOfCake/search), [Validator](https://api.cakephp.org/5.0/class-Cake.Validation.Validator.html), and [Bake](#bake-theme). - Provides additional functionality through Attributes and Doc Blocks. The current release is for CakePHP 5 and PHP 8.1, see previous releases for older versions of CakePHP and PHP. VersionBranchCake VersionPHP Version3.\*master^5.0^8.12.\*[2.x](https://github.com/cnizzardini/cakephp-swagger-bake/tree/2.x)^4.2^8.01.\*[1.next](https://github.com/cnizzardini/cakephp-swagger-bake/tree/1.next)^4.0^7.2Check out the demo applications for examples. DemosSource[Swagger Bake v3 demo](http://cakephpswaggerbake.cnizz.com/)[MixerAPI + Swagger Bake demo (v3)](https://demo.mixerapi.com/)v2 demov1 demoTable of Contents ----------------- [](#table-of-contents) - [Installation](#installation) - [Getting Started](#getting-started) - [Attributes](#attributes) - [Events](#event-system) - [Customizing Exception Responses](#customizing-exception-response-samples) - [Extending Views and Controllers](#extending-views-and-controllers) - [Multiple Instances of SwaggerBake](#multiple-instances-of-swagger-bake) - [Debug Commands](#debug-commands) - [Bake Theme](#bake-theme) - [Common Issues](#common-issues) - [Contributing](#contribute) Installation ------------ [](#installation) You can install via the [composer](https://getcomposer.org/) dependency manager: ``` composer require cnizzardini/cakephp-swagger-bake ``` Next load the plugin via `bin/cake plugin load SwaggerBake` or if you prefer manually: ``` # src/Application.php public function bootstrap(): void { // other logic... $this->addPlugin('SwaggerBake'); } ``` For standard applications that have not split their API into plugins, the automated setup is the easiest. Otherwise, skip to the manual setup. ### Automated Setup [](#automated-setup) Use the `swagger install` command and then [add a route](#add-route). ``` bin/cake swagger install ``` ### Manual Setup [](#manual-setup) - Create a base [swagger.yml](assets/swagger.yml) file at `config\swagger.yml`. An example file is provided [here](assets/swagger.yml). - Create a [swagger\_bake.php](assets/swagger_bake.php) config file at `config/swagger_bake.php` file. See the example file [here](assets/swagger_bake.php) for further explanation. Then just [add a route](#add-route). For more read sections on [Multiple Instances of SwaggerBake](#multiple-instances-of-swagger-bake)and [Extending Views and Controllers](#extending-views-and-controllers) ### Add Route [](#add-route) Create a route for the SwaggerUI page in `config/routes.php`, example: ``` $builder->connect( '/api', # this will be the "homepage" for your Swagger or Redoc UI ['plugin' => 'SwaggerBake', 'controller' => 'Swagger', 'action' => 'index'] ); ``` You can now browse to either `/api` for swagger or `/api?doctype=redoc` for redoc. Your OpenAPI JSON will exist at `/api/swagger.json`. Getting Started --------------- [](#getting-started) - You can generate OpenAPI json from the command line at anytime by running the `swagger bake` command: ``` bin/cake swagger bake ``` - If Hot Reload is enabled ([see config](assets/swagger_bake.php)) OpenAPI will be generated each time you browse to SwaggerUI (or Redoc) in your web browser. - You can also generate OpenAPI programmatically: ``` $swagger = (new \SwaggerBake\Lib\SwaggerFactory())->create()->build(); $swagger->getArray(); # returns swagger array $swagger->toString(); # returns swagger json $swagger->writeFile('/full/path/to/your/swagger.json'); # writes swagger.json ``` - Checkout the [debug commands](#debug-commands) for troubleshooting and the [bake theme](#bake-theme) for generating RESTful controllers. ### Routes [](#routes) Your [RESTful routes](https://book.cakephp.org/5/en/development/routing.html#restful-routing) are used to build OpenAPI paths and operations. ### Controllers [](#controllers) SwaggerBake will parse the [DocBlocks](https://docs.phpdoc.org/latest/guides/docblocks.html) on your controller actions for additional OpenAPI data. ``` /** * OpenAPI Operation Summary * * This displays as the operations long description * * @link https://book.cakephp.org/5/en/index.html External documentation * @deprecated Indicates the operation is deprecated * @throws \Cake\Http\Exception\BadRequestException Appears as 400 response with this description * @throws \Exception Appears as 500 response with this description */ public function index() {} ``` If you prefer, you may use the [OpenApiOperation](docs/attributes.md#OpenApiOperation), [OpenApiResponse](docs/attributes.md#OpenApiResponse) attributes instead. These attributes take precedence over doc block parsing. Read below for a full list of attributes. ### Models [](#models) OpenAPI schema is built from your Table and Entity classes and any validators you've defined in them. You may adjust the default schema using the [OpenApiSchema](docs/attributes.md#OpenApiSchema) and [OpenApiSchemaProperty](docs/attributes.md#OpenApiSchemaProperty) attributes. Attributes ---------- [](#attributes) For additional functionality the following [PHP8 Attributes](https://www.php.net/manual/en/language.attributes.overview.php)may be used. These can be imported individually from the `SwaggerBake\Lib\Attribute` namespace. [Read the Attributes docs](docs/attributes.md) for detailed examples. If you are using [version 1](https://github.com/cnizzardini/cakephp-swagger-bake/tree/1.next) you will need to use annotations. AttributeUsageDescription[OpenApiDto](docs/attributes.md#OpenApiDto)Controller ActionBuilds OpenAPI query params and request bodies from Data Transfer Objects[OpenApiForm](docs/attributes.md#OpenApiForm)Controller ActionBuilds OpenAPI for application/x-www-form-urlencoded request bodies[OpenApiHeader](docs/attributes.md#OpenApiHeader)Controller ActionCreate OpenAPI header parameters[OpenApiOperation](docs/attributes.md#OpenApiOperation)Controller ActionModifies OpenAPI operation[OpenApiPaginator](docs/attributes.md#OpenApiPaginator)Controller ActionCreate OpenAPI query params from CakePHP Paginator Component[OpenApiPath](docs/attributes.md#OpenApiPath)ControllerModifies OpenAPI paths[OpenApiPathParam](docs/attributes.md#OpenApiPathParam)Controller ActionModify an existing OpenAPI path parameter[OpenApiQueryParam](docs/attributes.md#OpenApiQueryParam)Controller ActionBuilds OpenAPI query param[OpenApiRequestBody](docs/attributes.md#OpenApiRequestBody)Controller ActionModify OpenAPI request body[OpenApiResponse](docs/attributes.md#OpenApiResponse)Controller ActionModify OpenAPI response[OpenApiSchema](docs/attributes.md#OpenApiSchema)EntityModifies OpenAPI schema[OpenApiSchemaProperty](docs/attributes.md#OpenApiSchemaProperty)Entity or ClassModifies an OpenAPI schema property or defines OpenApiResponse schema[OpenApiSearch](docs/attributes.md#OpenApiSearch)Controller ActionCreate OpenAPI query params from CakePHP Search plugin[OpenApiSecurity](docs/attributes.md#OpenApiSecurity)Controller ActionCreate/modify OpenAPI securityEvent System ------------ [](#event-system) SwaggerBake comes with an [event system](docs/events.md) to allow for further control over your OpenAPI schema. EventDescription[SwaggerBake.Operation.created](docs/events.md#operation-created)Dispatched each time an OpenAPI Path > Operation is created[SwaggerBake.Path.created](docs/events.md#path-created)Dispatched each time an OpenAPI Path is created[SwaggerBake.Schema.created](docs/events.md#schema-created)Dispatched each time an OpenAPI Schema is created[SwaggerBake.initialize](docs/events.md#initialize)Dispatched during initialization phase on SwaggerBake[SwaggerBake.beforeRender](docs/events.md#before-render)Dispatched before SwaggerBake outputs OpenAPI JSONCustomizing Exception Response Samples -------------------------------------- [](#customizing-exception-response-samples) By default, SwaggerBake uses `'#/components/schemas/Exception'` as your OpenAPI documentations Exception schema. See the default [swagger.yml](assets/swagger.yml) and `exceptionSchema` in [swagger\_bake.php](assets/swagger_bake.php) for more info. You can further customize with attributes and `@throws`. ### OpenApiResponse [](#openapiresponse) Using the `ref` or `schema` properties of [OpenApiResponse](docs/attributes.md#OpenApiResponse). ### Using the `@throws` tag and OpenApiExceptionSchemaInterface [](#using-the-throws-tag-and-openapiexceptionschemainterface) Implement `SwaggerBake\Lib\OpenApiExceptionSchemaInterface` on your exception class, then document the exception with a `@throws` tag in your controller action's doc block. ``` /** * @throws \App\Exception\MyException */ public function add(){} ``` Example exception class: ``` class MyException implements OpenApiExceptionSchemaInterface { public static function getExceptionCode(): string { return '400'; } public static function getExceptionDescription(): ?string { return 'An optional description'; // returning null omits the response description } public static function getExceptionSchema(): Schema|string { return (new \SwaggerBake\Lib\OpenApi\Schema()) ->setTitle('MyException') ->setProperties([ (new SchemaProperty())->setType('string')->setName('code')->setExample('400'), (new SchemaProperty())->setType('string')->setName('message')->setExample('error'), (new SchemaProperty())->setType('string')->setName('wherever')->setExample('whatever you want') ]); } } ``` Extending Views and Controllers ------------------------------- [](#extending-views-and-controllers) It's possible to write extensions for SwaggerBake. Read the [extension documentation](docs/extensions.md). There are several other options to extend functionality documented below: #### Using Your Own SwaggerUI [](#using-your-own-swaggerui) You may use your own swagger or redoc install in lieu of the version that comes with SwaggerBake. Simply don't add a custom route as indicated in the installation steps. In this case just reference the generated swagger.json within your userland Swagger UI install. #### Using Your Own Controller [](#using-your-own-controller) You might want to perform some additional logic (checking for authentication) before rendering the built-in Swagger UI. This is easy to do. Just create your own route and controller, then reference the built-in layout and template: ``` // config/routes.php $builder->connect( '/my-swagger-docs', ['controller' => 'MySwagger', 'action' => 'index'] ); ``` To get started, copy [SwaggerController](src/Controller/SwaggerController.php) into your project. #### Using Your Own Layout and Templates [](#using-your-own-layout-and-templates) You will need to use your own controller (see above). From there you can copy the [layouts](templates/layout) and [templates](templates/Swagger) into your project and inform your controller action to use them instead. Checkout out the CakePHP documentation on [Views](https://book.cakephp.org/5/en/views.html) for specifics. This can be useful if you'd like to add additional functionality to SwaggerUI (or Redoc) using their APIs or if your project is not installed in your web servers document root (i.e. a sub-folder). Multiple Instances of Swagger Bake ---------------------------------- [](#multiple-instances-of-swagger-bake) If your application has multiple APIs that are split into plugins you can generate unique OpenAPI schema, Swagger UI, and Redoc for each plugin. Setup a new `swagger_bake.php` and `swagger.yaml` in `plugins/OtherApi/config`. These configurations should point to your plugins paths and namespaces. Next, create a custom [SwaggerController](src/Controller/SwaggerController.php) and load the configuration within `initialize()`: ``` public function initialize(): void { parent::initialize(); Configure::load('OtherApi.swagger_bake', 'default', false); // note: `false` for the third argument is important } ``` When running `bin/cake swagger bake` you will need to specify your plugins swagger\_bake config: ``` bin/cake swagger bake --config OtherApi.swagger_bake ``` Debug Commands -------------- [](#debug-commands) In addition to `swagger bake` these console helpers provide insight into how your Swagger documentation is generated. #### `swagger routes` [](#swagger-routes) Displays a list of routes that can be viewed in Swagger. ``` bin/cake swagger routes ``` #### `swagger models` [](#swagger-models) Displays a list of models that can be viewed in Swagger. ``` bin/cake swagger models ``` Bake Theme ---------- [](#bake-theme) SwaggerBake comes with [Bake templates](templates/bake) for scaffolding RESTful controllers compatible with SwaggerBake and OpenAPI 3.0 schema. Using the bake theme is completely optional, but will save you some time since the default bake theme is not specifically designed for RESTful APIs. ``` bin/cake bake controller {Name} --theme SwaggerBake ``` Common Issues ------------- [](#common-issues) ### Swagger UI [](#swagger-ui) `No API definition provided.` Verify that swagger.json exists. ### SwaggerBakeRunTimeExceptions [](#swaggerbakeruntimeexceptions) `Unable to create swagger file. Try creating an empty file first or checking permissions` Create the swagger.json manually matching the path in your `config/swagger_bake.php` file. `Output file is not writable` Change permissions on your `swagger.json file`, `764` should do. `Controller not found` Make sure a controller actually exists for the route resource. ### Missing routes [](#missing-routes) Make sure yours route are properly defined in `config/routes.php` per the [CakePHP RESTful routing](https://book.cakephp.org/5/en/development/routing.html#restful-routing) documentation. ### Missing request or response samples [](#missing-request-or-response-samples) Sample schema is determined using [CakePHP naming conventions](https://book.cakephp.org/5/en/intro/conventions.html). Does your controller name match your model names? For customizing response schema see [OpenApiResponse](docs/attributes.md#OpenApiResponse). ### Missing request schema [](#missing-request-schema) Sample schema is determined using [CakePHP naming conventions](https://book.cakephp.org/5/en/intro/conventions.html). Does your controller name match your model names? For customizing request schema see [OpenApiRequestBody](docs/attributes.md#OpenApiRequestBody). ### Missing CSRF token body [](#missing-csrf-token-body) Either disable CSRF protection on your main route in `config/routes.php` or enable CSRF protection in Swagger UI. The library does not currently support adding this in for you. ### HTTP DELETE issues with Swagger UI [](#http-delete-issues-with-swagger-ui) Swagger UI sends HTTP DELETE without an `accept` header. If the record does not exist, an exception is generated. This results in an HTML response being generated which can be quite large and cause the UI to be slow to render. To get around this you can force an `accept` value on the header using the CakePHP middleware: ``` # src/Application.php public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue { $middlewareQueue ->add(function(ServerRequestInterface $request, RequestHandlerInterface $handler){ $accept = $request->getHeader('accept'); if ($request->getMethod() === 'DELETE' && reset($accept) === '*/*') { $request = $request->withHeader('accept', 'application/json'); } return $handler->handle($request); }); // other middleware... return $middlewareQueue; } ``` Read more about [CakePHP middleware](https://book.cakephp.org/5/en/controllers/middleware.html) in the official documentation. Contribute ---------- [](#contribute) Send pull requests to help improve this library. You can include SwaggerBake in your primary Cake project as a local source to make developing easier: - Make a fork of this repository and clone it to your localhost - Remove `cnizzardini\cakephp-swagger-bake` from your `composer.json` - Add a paths repository to your `composer.json` ``` "minimum-stability": "dev", "repositories": [ { "type": "path", "url": "/absolute/local-path-to/cakephp-swagger-bake", "options": { "symlink": true } } ] ``` - Run `composer require cnizzardini/cakephp-swagger-bake @dev` Undo these steps when you're done. Read the full composer documentation on loading from path here: Check out the [extensions](docs/extensions.md) documentation to add functionality to this project. ### Tests + Analysis [](#tests--analysis) PHPUnit Test Suite: ``` composer test ``` PHPUnit, PHPCS, PHPSTAN, and PHPMD: ``` composer analyze ``` ### Health Score 64 — FairBetter than 99% of packages Maintenance82 Actively maintained with recent releases Popularity48 Moderate usage in the ecosystem Community29 Small or concentrated contributor base Maturity82 Battle-tested with a long release history Bus Factor1 Top contributor holds 97.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~19 days Recently: every ~77 days Total 111 Last Release 92d ago Major Versions v1.7.9 → v2.4.102022-10-29 v1.7.11 → v2.5.12022-12-14 v2.5.8 → v3.0.02024-01-11 v2.5.9 → v3.0.12024-02-25 2.x-dev → v3.1.02025-02-07 PHP version history (3 changes)v1-beta-0PHP >=7.2 v2.0.0PHP ^8.0 v3.0.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/171294?v=4)[Chris Nizzardini](/maintainers/cnizzardini)[@cnizzardini](https://github.com/cnizzardini) --- Top Contributors [![cnizzardini](https://avatars.githubusercontent.com/u/171294?v=4)](https://github.com/cnizzardini "cnizzardini (891 commits)")[![bmudda](https://avatars.githubusercontent.com/u/1568534?v=4)](https://github.com/bmudda "bmudda (5 commits)")[![jamisonbryant](https://avatars.githubusercontent.com/u/6774110?v=4)](https://github.com/jamisonbryant "jamisonbryant (4 commits)")[![segy](https://avatars.githubusercontent.com/u/1355459?v=4)](https://github.com/segy "segy (3 commits)")[![lpj145](https://avatars.githubusercontent.com/u/11980109?v=4)](https://github.com/lpj145 "lpj145 (1 commits)")[![MasaKni](https://avatars.githubusercontent.com/u/65139438?v=4)](https://github.com/MasaKni "MasaKni (1 commits)")[![nomahideki](https://avatars.githubusercontent.com/u/28497951?v=4)](https://github.com/nomahideki "nomahideki (1 commits)")[![TheGlenn88](https://avatars.githubusercontent.com/u/5333026?v=4)](https://github.com/TheGlenn88 "TheGlenn88 (1 commits)")[![adrian-tiberius](https://avatars.githubusercontent.com/u/1635084?v=4)](https://github.com/adrian-tiberius "adrian-tiberius (1 commits)")[![ThierryAgueda](https://avatars.githubusercontent.com/u/120493722?v=4)](https://github.com/ThierryAgueda "ThierryAgueda (1 commits)")[![ArchangelDesign](https://avatars.githubusercontent.com/u/8267447?v=4)](https://github.com/ArchangelDesign "ArchangelDesign (1 commits)")[![dogmatic69](https://avatars.githubusercontent.com/u/94674?v=4)](https://github.com/dogmatic69 "dogmatic69 (1 commits)")[![JulyanoF](https://avatars.githubusercontent.com/u/17284704?v=4)](https://github.com/JulyanoF "JulyanoF (1 commits)") --- Tags cake-plugincakephpcakephp-apicakephp-plugincakephp4openapiredocswagger-bakeswagger-documentationswagger-uicakephp swaggercake swaggercakephp5 swaggercakephp openapicakephp5 openapicake openapi ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/cnizzardini-cakephp-swagger-bake/health.svg) ``` [![Health](https://phpackages.com/badges/cnizzardini-cakephp-swagger-bake/health.svg)](https://phpackages.com/packages/cnizzardini-cakephp-swagger-bake) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k34.0M112](/packages/darkaonline-l5-swagger)[googleads/googleads-php-lib Google Ad Manager SOAP API Client Library for PHP 67410.3M25](/packages/googleads-googleads-php-lib)[code-lts/doctum Doctum, a PHP API documentation generator. Fork of Sami 35077.9k31](/packages/code-lts-doctum)[onmoon/openapi-server-bundle Symfony bundle to create a fully-featured API server from an OpenAPI v3 specification 1117.7k](/packages/onmoon-openapi-server-bundle)[allansun/openapi-parser A universal OpenAPI (Swagger) schema parser 1212.3k91](/packages/allansun-openapi-parser) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)