将 Swagger UI 与 Codeigniter4 集成

Swagger 是一种广泛使用的 API 文档和测试工具，可与 Laravel、Spring Boot、CodeIgniter 和 ExpressJS 等流行的 Web 框架无缝集成。在本文中，我们将重点介绍 Swagger 与 CodeIgniter 的集成。

安装依赖项：

composer require zircote/swagger-php doctrine/annotations

下载 SwaggerUI .zip 或 SwaggerUI GitHub 存储库：

• 下载链接：SwaggerUI 最新版本 下载最适合您要求的 Swagger UI 版本。

编写控制器：

要为 Swagger UI 生成 swagger.json 文件，我们必须创建一个控制器。根据您的选择将控制器命名为 SwaggerDocGenerator.php。在控制器中，我们必须使用 zircote/swagger-php 中的 OpenApiGenerator 将所有 @OA 语法转换为 JSON。

<?php
namespace App\Controllers;

use OpenApi\Generator;

class SwaggerDocGenerator extends BaseController
{
    /**
     * Generate OpenAPI documentation for the API ...
     * @return string
     */
    public function generate(): string
    {
        // Specify the path where your API controllers are located
        $openapi = Generator::scan([APPPATH . 'Controllers']);

        $swaggerContent = $openapi->toJson();

        // Save the generated OpenAPI content to a file
        $filePath = FCPATH . 'swagger_ui/swagger.json';
        file_put_contents($filePath, $swaggerContent);

        return $swaggerContent;
    }

    /**
     * Render the SwaggerUI ...
     * @return string
     */
    public function index()
    {
        return view('swagger_docs/index');
    }
}

?>

创建路线：

通过在 Config/Routes.php 上创建路由，我们将能够生成预期的 sawgger.json 文件。

// Create API documentation ...
$routes->get('api/v1/docs/generate', 'SwaggerDocGenerator::generate');
$routes->get('api/v1/docs/ui', 'SwaggerDocGenerator::index');

渲染 Swagger UI：

有多种方法可以将 swagger.json 文件渲染到 SwaggerUI 中：

• 将 swagger.json 文件导入 POSTMAN。
• 使用 SwaggerUI 和您自己的视图来渲染 SwaggerUI。
• 在前端应用程序中设置环境，以通过请求后端 API 获取 swagger.json 文件来呈现 SwaggerUI。

在这里，我们将看到前两种方式。我们将在另一篇文章中讨论第三种方式。

将 swagger.json 文件导入到 POSTMAN 中：

• 复制 swagger.json。
• 打开邮递员。
• 点击左上角的导入按钮。
• 粘贴复制的 swagger.json。

将 SwaggerUI 与您自己的视图一起使用来呈现 SwaggerUI：

• 在视图文件夹 app/Views/swagger_docs/index.php 中创建一个 .php 文件来渲染 SwaggerUI。
• 将下载的 SwaggerUI .zip 文件解压到 public/swagger_ui/ 文件夹中。

composer require zircote/swagger-php doctrine/annotations

笔记：

• 确保运行 php Sparkserve 命令来运行 Codeigniter4 应用程序。
• 每次更改 OpenAPI 文档语法时，都必须运行 http://localhost:8080/api/v1/docs/generate URL 来生成更新的 swagger.json 文件。
• 确保使用 swagger.json 文件的更新 URL 更新 swagger-initializer.js 文件。

结论：

在本文中，我们探索了将 Swagger 与 CodeIgniter 4 集成，生成 swagger.json 文件，在 Swagger UI 中渲染它，并将其导入 Postman。我们还演示了如何在自定义视图中呈现 Swagger UI。然而，手动生成 swagger.json 文件并更新 swagger-initializer.js 文件中的 URL 并不理想。

在下一篇文章中，我将演示使用自定义 CLI 命令自动化此过程，并旨在为此目的开发一个开源包。欢迎在评论部分分享您的建议或疑问。

以上是将 Swagger UI 与 Codeigniter4 集成的详细内容。更多信息请关注PHP中文网其他相关文章！