README

CakePHP 4.x 插件，使用 swagger-php 和 swagger-ui 为您的项目自动生成 Swagger 2.0 文档。

要求

CakePHP 4.0+
了解一些 swagger-php 注释知识

安装

使用 composer 安装插件

composer require alt3/cakephp-swagger

启用

在 src/Application.php 中的 bootstrap() 方法中启用插件

    public function bootstrap()
    {
        parent::bootstrap();
        $this->addPlugin('Alt3/Swagger');
    }

同时确保在 Application.php 中加载了 AssetMiddleware，否则所有 Swagger 页面资源将返回 404。

安装检查

启用插件后，访问 http://your.app/alt3/swagger 应该会生成 Swagger-UI 界面

配置

此插件的全部配置都通过 /config/swagger.php 配置文件完成。以下是完整的示例。

<?php
use Cake\Core\Configure;

return [
    'Swagger' => [
        '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 部分

使用 ui 部分来自定义以下 Swagger-UI 选项

title: 设置 Swagger-UI 页面标题，默认为 cakephp-swagger
validator: 显示/隐藏验证器图像，默认为 true
api_selector: 显示/隐藏 API 选择器表单字段，默认为 true
route: 使用自定义路由公开 UI，默认为 /alt3/swagger/
schemes: 数组用于指定用于生成 BASE URL 的第三个字段 (host 是实时获取的，如果未通过注释定义，则实时获取 basePath)，默认为 null

请注意，UI 将自动加载库中找到的第一个文档。

文档部分

使用 docs 部分来自定义以下选项

crawl: 启用爬虫以生成新文档而不是从文件系统提供，默认为 true
route: 使用自定义路由公开文档，默认为 /alt3/swagger/docs/
cors: 指定与 json 响应一起发送的 CORS 标头，默认为 null

库部分

使用 library 部分指定一个或多个 Swagger 文档，这样

swagger-php 就知道要解析哪些文件和文件夹以获取注释
swagger-php 可以生成 Swagger json
此插件可以在 http://your.app/alt3/swagger/docs/:id 处公开 json (因此它可以用作 UI)

以下库示例将导致

swagger-php 扫描在 include 中定义的所有文件和文件夹
swagger-php 忽略在 exclude 中定义的所有文件和文件夹
两个端点提供 json Swagger 文档
- http://your.app/alt3/swagger/docs/api
- http://your.app/alt3/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'
        ]
    ]
]

它还会使 http://your.app/alt3/swagger/docs 生成一个 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

此插件附带一个 shell，该 shell 应该可以简化生产环境中的部署。只需运行以下命令即可在 tmp/cache 中创建以 cakephp_swagger 前缀命名的文件系统文档，其中包含您库中找到的所有实体。

bin/cake swagger makedocs <host>

需要主机参数（例如 your.app.com），不应包含协议，并用于在 Swagger 文档中设置 host 属性。

快速入门注释示例

解释 swagger-php 注解的魔法超出了这个插件的功能，但在您创建第一个库文档时，您可能希望将以下工作示例复制/粘贴到您的任何PHP文件中，以便给您一个良好的起点。

注意：非星号（*）的奇怪语法确保了与 CakePHP 代码检查器的兼容性。

<?php
/**
    @SWG\Swagger(
        @SWG\Info(
            title="cakephp-swagger",
            description="Quickstart annotation example",
            termsOfService="https://swagger.org.cn/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"
        )
    )
*/

这应该会产生以下结果

贡献

在提交PR之前，请确保

PHPUnit 和 CakePHP 代码检查器测试通过
Coveralls 代码覆盖率保持100%

alt3 / cakephp-swagger

维护者

详细信息