Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alt3/cakephp-swagger
Swagger plugin for documenting your CakePHP APIs
https://github.com/alt3/cakephp-swagger
cakephp php swagger swagger-ui
Last synced: 27 days ago
JSON representation
Swagger plugin for documenting your CakePHP APIs
- Host: GitHub
- URL: https://github.com/alt3/cakephp-swagger
- Owner: alt3
- License: mit
- Created: 2015-11-07T15:29:59.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2022-05-11T12:11:31.000Z (over 2 years ago)
- Last Synced: 2024-10-02T18:37:26.563Z (2 months ago)
- Topics: cakephp, php, swagger, swagger-ui
- Language: JavaScript
- Homepage:
- Size: 2.45 MB
- Stars: 64
- Watchers: 7
- Forks: 17
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-cakephp - Alt3/Swagger plugin - Swagger 2.0 documentation for your CakePHP APIs using swagger-php and swagger-ui. (REST and API)
README
# cakephp-swagger
[](https://travis-ci.org/alt3/cakephp-swagger)
[](https://styleci.io/repos/45741948)
[](https://codecov.io/github/alt3/cakephp-swagger)
[](https://packagist.org/packages/alt3/cakephp-swagger)
[](LICENSE.txt)
CakePHP 4.x plugin that adds auto-generated Swagger 2.0 documentation to your projects using swagger-php and swagger-ui.
## Requirements
* CakePHP 4.0+
* Some [swagger-php](https://github.com/zircote/swagger-php) annotation knowledge
## Installation
Install the plugin using composer:
```bash
composer require alt3/cakephp-swagger
```
## Enabling
Enable the plugin in the `bootstrap()` method found in `src/Application.php`:
```php
public function bootstrap()
{
parent::bootstrap();
$this->addPlugin('Alt3/Swagger');
}
```
> Also make sure that AssetMiddleware is loaded inside `Application.php` or all Swagger page assets will 404.
## Installation check
After enabling the plugin, browsing to `http://your.app/alt3/swagger` should now produce the
[Swagger-UI](http://swagger.io/swagger-ui/) interface:
## Configuration
All configuration for this plugin is done through the `/config/swagger.php`
configuration file. TLDR full example below.
```php
[
'ui' => [
'title' => 'ALT3 Swagger',
'validator' => true,
'api_selector' => true,
'route' => '/swagger/',
'schemes' => ['http', 'https']
],
'docs' => [
'crawl' => Configure::read('debug'),
'route' => '/swagger/docs/',
'cors' => [
'Access-Control-Allow-Origin' => '*',
'Access-Control-Allow-Methods' => 'GET, POST',
'Access-Control-Allow-Headers' => 'X-Requested-With'
]
],
'library' => [
'api' => [
'include' => ROOT . DS . 'src',
'exclude' => [
'/Editor/'
]
],
'editor' => [
'include' => [
ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',
ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',
ROOT . DS . 'src' . DS . 'Model'
]
]
]
]
];
```
### UI section
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`
> Please note that the UI will auto-load the first document found in the library.
### Docs section
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/`
- `cors`: specify CORS headers to send with the json responses, defaults to `null`
### Library section
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)
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`
```php
'library' => [
'api' => [
'include' => ROOT . DS . 'src',
'exclude' => [
'/Editor/'
]
],
'editor' => [
'include' => [
ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',
ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',
ROOT . DS . 'src' . DS . 'Model'
]
]
]
```
It would also make `http://your.app/alt3/swagger/docs` produce a json list
with links to all available documents similar to the example below.
```json
{
"success": true,
"data": [
{
"document": "api",
"link": "http://your.app/alt3/swagger/docs/api"
},
{
"document": "editor",
"link": "http://your.app/alt3/swagger/docs/editor"
}
]
}
```
## SwaggerShell
This plugin comes with a shell that should simplify deployment in production
environments. Simply run the following command to create `cakephp_swagger`
prefixed filesystem documents in `tmp/cache` for all entities found in your
library.
```bash
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.
## Quickstart Annotation Example
Explaining [swagger-php](https://github.com/zircote/swagger-php)
annotation voodoo is beyond this plugin but to give yourself a head start while
creating your first library document you might want to copy/paste the following
working example into any of your php files.
> **Note**: the weird non-starred syntax ensures
> compatibility with the CakePHP Code Sniffer.
```php