Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cnizzardini/cakephp-swagger-bake
Automatically generate OpenAPI, Swagger, and Redoc documentation from your existing CakePHP code.
https://github.com/cnizzardini/cakephp-swagger-bake
cake-plugin cakephp cakephp-api cakephp-plugin cakephp4 openapi redoc swagger-bake swagger-documentation swagger-ui
Last synced: 3 days ago
JSON representation
Automatically generate OpenAPI, Swagger, and Redoc documentation from your existing CakePHP code.
- Host: GitHub
- URL: https://github.com/cnizzardini/cakephp-swagger-bake
- Owner: cnizzardini
- License: mit
- Created: 2020-04-10T23:27:29.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-02T02:36:14.000Z (2 months ago)
- Last Synced: 2024-12-02T05:04:39.261Z (11 days ago)
- Topics: cake-plugin, cakephp, cakephp-api, cakephp-plugin, cakephp4, openapi, redoc, swagger-bake, swagger-documentation, swagger-ui
- Language: PHP
- Homepage: http://cakephpswaggerbake.cnizz.com/
- Size: 8.56 MB
- Stars: 60
- Watchers: 7
- Forks: 20
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-cakephp - SwaggerBake plugin - This plugin automatically builds OpenAPI from your existing models and routes for display in Swagger and Redoc. (REST and API)
README
# Swagger Bake
#### A delightfully tasty plugin for generating OpenAPI, Swagger and Redoc
[](https://packagist.org/packages/cnizzardini/cakephp-swagger-bake)
[](https://github.com/cnizzardini/cakephp-swagger-bake/actions/workflows/push.yml)
[](https://coveralls.io/github/cnizzardini/cakephp-swagger-bake?branch=master)
[](http://mixerapi.com)
[](https://book.cakephp.org/5/en/index.html)
[](https://php.net/)
[](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.
| Version | Branch | Cake Version | PHP Version |
|---------|---------------------------------------------------------------------------|--------------|-------------|
| 3.* | master | ^5.0 | ^8.1 |
| 2.* | [2.x](https://github.com/cnizzardini/cakephp-swagger-bake/tree/2.x) | ^4.2 | ^8.0 |
| 1.* | [1.next](https://github.com/cnizzardini/cakephp-swagger-bake/tree/1.next) | ^4.0 | ^7.2 |
Check out the demo applications for examples.
| Demos | Source |
|-----------------------------------------------------------------|----------------------------------------------------------------------|
| [Swagger Bake v3 demo](http://cakephpswaggerbake.cnizz.com/) | https://github.com/cnizzardini/cakephp-swagger-bake-demo |
| [MixerAPI + Swagger Bake demo (v3)](https://demo.mixerapi.com/) | https://github.com/mixerapi/demo |
| v2 demo | https://github.com/cnizzardini/cakephp-swagger-bake-demo/tree/2.next |
| v1 demo | https://github.com/cnizzardini/cakephp-swagger-bake-demo/tree/1.next |
## 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
You can install via the [composer](https://getcomposer.org/) dependency manager:
```console
composer require cnizzardini/cakephp-swagger-bake
```
Next load the plugin via `bin/cake plugin load SwaggerBake` or if you prefer manually:
```php
# 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
Use the `swagger install` command and then [add a route](#add-route).
```console
bin/cake swagger install
```
### 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
Create a route for the SwaggerUI page in `config/routes.php`, example:
```php
$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
- You can generate OpenAPI json from the command line at anytime by running the `swagger bake` command:
```console
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:
```php
$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
Your [RESTful routes](https://book.cakephp.org/5/en/development/routing.html#restful-routing) are used to build
OpenAPI paths and operations.
### Controllers
SwaggerBake will parse the [DocBlocks](https://docs.phpdoc.org/latest/guides/docblocks.html) on your controller
actions for additional OpenAPI data.
```php
/**
* 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
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
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.
| Attribute | Usage | Description |
|-----------------------------------------------------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------|
| [OpenApiDto](docs/attributes.md#OpenApiDto) | Controller Action | Builds OpenAPI query params and request bodies from Data Transfer Objects |
| [OpenApiForm](docs/attributes.md#OpenApiForm) | Controller Action | Builds OpenAPI for application/x-www-form-urlencoded request bodies |
| [OpenApiHeader](docs/attributes.md#OpenApiHeader) | Controller Action | Create OpenAPI header parameters |
| [OpenApiOperation](docs/attributes.md#OpenApiOperation) | Controller Action | Modifies OpenAPI operation |
| [OpenApiPaginator](docs/attributes.md#OpenApiPaginator) | Controller Action | Create OpenAPI query params from CakePHP Paginator Component |
| [OpenApiPath](docs/attributes.md#OpenApiPath) | Controller | Modifies OpenAPI paths |
| [OpenApiPathParam](docs/attributes.md#OpenApiPathParam) | Controller Action | Modify an existing OpenAPI path parameter |
| [OpenApiQueryParam](docs/attributes.md#OpenApiQueryParam) | Controller Action | Builds OpenAPI query param |
| [OpenApiRequestBody](docs/attributes.md#OpenApiRequestBody) | Controller Action | Modify OpenAPI request body |
| [OpenApiResponse](docs/attributes.md#OpenApiResponse) | Controller Action | Modify OpenAPI response |
| [OpenApiSchema](docs/attributes.md#OpenApiSchema) | Entity | Modifies OpenAPI schema |
| [OpenApiSchemaProperty](docs/attributes.md#OpenApiSchemaProperty) | Entity or Class | Modifies an OpenAPI schema property or defines OpenApiResponse schema |
| [OpenApiSearch](docs/attributes.md#OpenApiSearch) | Controller Action | Create OpenAPI query params from CakePHP Search plugin |
| [OpenApiSecurity](docs/attributes.md#OpenApiSecurity) | Controller Action | Create/modify OpenAPI security |
## Event System
SwaggerBake comes with an [event system](docs/events.md) to allow for further control over your OpenAPI schema.
| Event | Description |
|-------------------------------------------------------------------|-------------------------------------------------------------|
| [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 JSON |
## 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
Using the `ref` or `schema` properties of [OpenApiResponse](docs/attributes.md#OpenApiResponse).
### 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.
```php
/**
* @throws \App\Exception\MyException
*/
public function add(){}
```
Example exception class:
```php
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
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
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
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:
```php
// 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
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
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()`:
```php
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:
```console
bin/cake swagger bake --config OtherApi.swagger_bake
```
## Debug Commands
In addition to `swagger bake` these console helpers provide insight into how your Swagger documentation is generated.
#### `swagger routes`
Displays a list of routes that can be viewed in Swagger.
```sh
bin/cake swagger routes
```
#### `swagger models`
Displays a list of models that can be viewed in Swagger.
```sh
bin/cake swagger models
```
## 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
### Swagger UI
`No API definition provided.`
Verify that swagger.json exists.
### 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
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
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
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
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
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:
```php
# 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
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:
[https://getcomposer.org/doc/05-repositories.md#path](https://getcomposer.org/doc/05-repositories.md#path)
Check out the [extensions](docs/extensions.md) documentation to add functionality to this project.
### Tests + Analysis
PHPUnit Test Suite:
```console
composer test
```
PHPUnit, PHPCS, PHPSTAN, and PHPMD:
```console
composer analyze
```
[GrumPHP](https://github.com/phpro/grumphp) can be used to run tests and static analyzers in a pre-commit hook.
```console
composer grumphp-init
```
I've set grumphp to be installed globally: https://github.com/phpro/grumphp/blob/master/doc/installation/global.md