README

一款令人愉悦的、用于生成 OpenAPI、Swagger 和 Redoc 的插件

从现有的 CakePHP 代码中自动生成 OpenApi、Swagger 和 Redoc 文档

• 从您的 RESTful 路由和控制器中创建 OpenApi 路径和操作。
• 从您的实体和表中创建 OpenApi 模式。
• 与： Paginator、friendsofcake/search、Validator 和 Bake 集成。
• 通过属性和文档块提供额外的功能。

当前版本适用于 CakePHP 5 和 PHP 8.1，有关 CakePHP 和 PHP 更旧版本的说明，请参阅之前的版本。

查看示例应用程序以获取示例。

目录

• 安装
• 入门指南
• 属性
• 事件
• 自定义异常响应
• 扩展视图和控制台
• SwaggerBake 的多个实例
• 调试命令
• 烘焙主题
• 常见问题
• 贡献

安装

您可以通过 composer 依赖管理器进行安装

composer require cnizzardini/cakephp-swagger-bake

然后通过 bin/cake plugin load SwaggerBake 加载插件，或者如果您更喜欢手动操作

# src/Application.php
public function bootstrap(): void
{
    // other logic...
    $this->addPlugin('SwaggerBake');
}

对于没有将 API 分离到插件的常规应用程序，自动设置是最简单的。否则，请跳转到手动设置。

自动设置

使用 swagger install 命令，然后 添加一个路由。

bin/cake swagger install

手动设置

• 在 config\swagger.yml 位置创建一个基本的 swagger.yml 文件。示例文件在这里提供 。

• 在 config/swagger_bake.php 文件中创建一个 swagger_bake.php 配置文件。有关进一步说明，请参阅示例文件 。 然后只需 添加一个路由。

有关更多关于 SwaggerBake 的多个实例 和 扩展视图和控制台 的信息，请参阅。

添加路由

在 config/routes.php 中创建一个用于 SwaggerUI 页面的路由，例如

$builder->connect(
    '/api', # this will be the "homepage" for your Swagger or Redoc UI
    ['plugin' => 'SwaggerBake', 'controller' => 'Swagger', 'action' => 'index']
);

现在您可以通过访问 /api 来浏览 swagger，或者通过 /api?doctype=redoc 来浏览 redoc。您的 OpenAPI JSON 将位于 /api/swagger.json。

入门指南

• 您可以通过运行 swagger bake 命令在任何时候从命令行生成 OpenAPI json。

bin/cake swagger bake

• 如果启用热重载（查看配置），每次您在浏览器中浏览到SwaggerUI（或Redoc）时，都会生成OpenAPI。

• 您也可以通过程序生成OpenAPI

$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

• 查看调试命令以进行故障排除和bake主题以生成RESTful控制器。

路由

您的RESTful路由用于构建OpenAPI路径和操作。

控制器

SwaggerBake将解析您控制器操作中的DocBlocks以获取额外的OpenAPI数据。

/**
 * OpenAPI Operation Summary
 * 
 * This displays as the operations long description
 * 
 * @link https://book.cakephp.com.cn/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() {}

如果您愿意，可以使用OpenApiOperation、OpenApiResponse属性代替。这些属性优先于doc块解析。请阅读下面的完整属性列表。

模型

OpenAPI模式由您的表和实体类以及您在它们中定义的任何验证器构建。您可以使用OpenApiSchema和OpenApiSchemaProperty属性调整默认模式。

属性

为了获得更多功能，可以使用以下PHP8属性。这些可以从SwaggerBake\Lib\Attribute命名空间单独导入。阅读属性文档以获取详细示例。如果您使用的是版本1，则需要使用注释。

事件系统

SwaggerBake提供了一个事件系统，以允许进一步控制您的OpenAPI模式。

自定义异常响应示例

默认情况下，SwaggerBake使用'#/components/schemas/Exception'作为您的OpenAPI文档的异常模式。有关更多信息，请参阅默认的swagger.yml和swagger_bake.php中的exceptionSchema。您可以使用属性和@throws进一步自定义。

OpenApiResponse

使用OpenApiResponse的ref或schema属性。

使用@throws标签和OpenApiExceptionSchemaInterface

在您的异常类上实现SwaggerBake\Lib\OpenApiExceptionSchemaInterface，然后在控制器操作的doc块中使用@throws标签记录异常。

/**
 * @throws \App\Exception\MyException
 */
public function add(){}

示例异常类

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')
            ]);
    }
}

扩展视图和控制台

可以为SwaggerBake编写扩展。请参阅扩展文档。以下还有其他几种扩展功能的方法。

使用您自己的SwaggerUI

您可以使用自己的swagger或redoc安装，而不是SwaggerBake中包含的版本。只需不要按照安装步骤添加自定义路由即可。在这种情况下，只需在您的用户land Swagger UI安装中引用生成的swagger.json即可。

使用您自己的控制器

您可能想在渲染内置Swagger UI之前执行一些额外的逻辑（例如检查身份验证）。这很容易做到。只需创建自己的路由和控制器，然后参考内置布局和模板即可。

// config/routes.php
$builder->connect(
    '/my-swagger-docs', 
    ['controller' => 'MySwagger', 'action' => 'index']
);

要开始使用，请将 SwaggerController 复制到您的项目中。

使用您自己的布局和模板

您需要使用自己的控制器（见上方）。从那里开始，您可以复制 布局 和 模板 到您的项目中，并通知控制器操作使用它们。有关详细信息，请参阅 CakePHP 文档中的 视图。如果您想通过他们的 API 向 SwaggerUI（或 Redoc）添加额外功能，或者您的项目未安装在您的 web 服务器文档根目录中（例如，子文件夹），这将非常有用。

Swagger Bake 的多个实例

如果您的应用程序有多个 API 并且它们被拆分为插件，您可以分别为每个插件生成唯一的 OpenAPI 架构、Swagger UI 和 Redoc。在 plugins/OtherApi/config 中设置新的 swagger_bake.php 和 swagger.yaml。这些配置应指向您的插件路径和命名空间。接下来，创建一个自定义的 SwaggerController 并在 initialize() 中加载配置。

    public function initialize(): void
    {
        parent::initialize();
        Configure::load('OtherApi.swagger_bake', 'default', false); // note: `false` for the third argument is important         
    }

在运行 bin/cake swagger bake 时，您需要指定您的插件 swagger_bake 配置

bin/cake swagger bake --config OtherApi.swagger_bake

调试命令

除了 swagger bake 之外，这些控制台助手还可以提供有关您的 Swagger 文档如何生成的见解。

swagger 路由

显示可以在 Swagger 中查看的路由列表。

bin/cake swagger routes

swagger 模型

显示可以在 Swagger 中查看的模型列表。

bin/cake swagger models

烘焙主题

SwaggerBake 随带 Bake 模板，用于构建与 SwaggerBake 和 OpenAPI 3.0 架构兼容的 RESTful 控制器。使用 bake 主题完全是可选的，但可以节省您一些时间，因为默认的 bake 主题并不是专门为 RESTful API 设计的。

bin/cake bake controller {Name} --theme SwaggerBake

常见问题

Swagger UI

未提供 API 定义。

请检查是否已存在 swagger.json。

SwaggerBakeRunTimeExceptions

无法创建 swagger 文件。请先尝试创建一个空文件，或检查权限

手动创建 swagger.json，使其与您的 config/swagger_bake.php 文件中的路径相匹配。

输出文件不可写

更改您的 swagger.json 文件 的权限，764 应该可以。

找不到控制器

请确保存在实际为路由资源创建的控制器。

缺少路由

请确保您的路由已按 CakePHP RESTful 路由 文档中的规定正确定义在 config/routes.php 中。

缺少请求或响应样本

样本架构是通过使用 CakePHP 命名约定 确定的。您的控制器名称是否与模型名称匹配？有关自定义响应架构，请参阅 OpenApiResponse。

缺少请求架构

样本架构是通过使用 CakePHP 命名约定 确定的。您的控制器名称是否与模型名称匹配？有关自定义请求架构，请参阅 OpenApiRequestBody。

缺少 CSRF 令牌正文

您可以在 config/routes.php 中禁用主路由的 CSRF 保护，或者启用 Swagger UI 的 CSRF 保护。该库目前不支持为您添加此功能。

Swagger UI 的 HTTP DELETE 问题

Swagger UI 在发送 HTTP DELETE 请求时没有使用 accept 头。如果记录不存在，会生成一个异常。这会导致生成一个相当大的 HTML 响应，从而使 UI 渲染变慢。为了解决这个问题，您可以使用 CakePHP 中间件强制在头中使用 accept 值。

# 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;
}

在官方文档中阅读有关 CakePHP 中间件 的更多信息。

贡献

发送拉取请求以帮助改进此库。您可以将 SwaggerBake 包含在您的 Cake 项目中作为本地源，以便于开发。

• 为此存储库创建一个分支，并将其克隆到您的本地主机。

• 从您的 composer.json 中删除 cnizzardini\cakephp-swagger-bake。

• 将路径存储库添加到您的 composer.json 中。

"minimum-stability": "dev",
"repositories": [
    {
        "type": "path",
        "url": "/absolute/local-path-to/cakephp-swagger-bake",
        "options": {
          "symlink": true
        }
    }
]

• 运行 composer require cnizzardini/cakephp-swagger-bake @dev。

完成操作后，撤销这些步骤。有关从这里加载的完整 composer 文档，请参阅：[https://getcomposer.org.cn/doc/05-repositories.md#path](https://getcomposer.org.cn/doc/05-repositories.md#path)

查看 扩展 文档，以向此项目添加功能。

测试 + 分析

PHPUnit 测试套件

composer test

PHPUnit、PHPCS、PHPSTAN 和 PHPMD

composer analyze

可以使用 GrumPHP 在 pre-commit 钩子中运行测试和静态分析器。

composer grumphp-init

我已经将 grumphp 设置为全局安装：[https://github.com/phpro/grumphp/blob/master/doc/installation/global.md](https://github.com/phpro/grumphp/blob/master/doc/installation/global.md)