README

CakePHP 5.x plugin that adds auto-generated Swagger 2.0 documentation to your projects using swagger-php and swagger-ui.

Requirements

CakePHP 5.0+
Some swagger-php annotation knowledge

Installation

Install the plugin using composer:

composer require cstaf/cakephp-swagger

Enabling

Enable the plugin in the bootstrap() method found in src/Application.php:

    public function bootstrap()
    {
        parent::bootstrap();
        $this->addPlugin('Cstaf/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/swagger should now produce the Swagger-UI interface:

Configuration

All configuration for this plugin is done through the /config/swagger.php configuration file. TLDR full example below.

<?php
use Cake\Core\Configure;

return [
    'Swagger' => [
        'ui' => [
            'title' => '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 /swagger/
schemes: array used to specify third field (host is fetched realtime, basePath is also fetched realtime if not), 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 /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/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/swagger/docs/api
- http://your.app/swagger/docs/editor

'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/swagger/docs produce a json list with links to all available documents similar to the example below.

{
    "success": true,
    "data": [
        {
            "document": "api",
            "link": "http://your.app/swagger/docs/api"
        },
        {
            "document": "editor",
            "link": "http://your.app/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.

bin/cake swagger makedocs <host>

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 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
/**
    @SWG\Swagger(
        @SWG\Info(
            title="cakephp-swagger",
            description="Quickstart annotation example",
            termsOfService="http://swagger.io/terms/",
            version="1.0.0"
        )
    )

    @SWG\Get(
        path="/cocktails",
        summary="Retrieve a list of cocktails",
        tags={"cocktail"},
        consumes={"application/json"},
        produces={"application/json"},
        @SWG\Parameter(
            name="sort",
            description="Sort results by field",
            in="query",
            required=false,
            type="string",
            enum={"name", "description"}
        ),
        @SWG\Response(
            response="200",
            description="Successful operation",
            @SWG\Schema(
                type="object",
                ref="#/definitions/Cocktail"
            )
        ),
        @SWG\Response(
            response=429,
            description="Rate Limit Exceeded"
        )
    )

    @SWG\Definition(
        definition="Cocktail",
        required={"name", "description"},
        @SWG\Property(
            property="id",
            type="integer",
            description="CakePHP record id"
        ),
        @SWG\Property(
            property="name",
            type="string",
            description="CakePHP name field"
        ),
        @SWG\Property(
            property="description",
            type="string",
            description="Description of a most tasty cocktail"
        )
    )
*/

Which should result in:

cstaf/cakephp-swagger

包简介

README 文档