如何在Lumen/Laravel中为REST API集成Swagger Editor？

当然有，以下是在Lumen中集成Swagger Editor并生成规范API文档的实操步骤：

1. 安装Swagger PHP依赖 #

首先安装用于通过代码注释生成OpenAPI规范的工具包：

composer require zircote/swagger-php --dev

2. 为API添加OpenAPI注释 #

在你的控制器方法上添加符合OpenAPI 3.0规范的注释，示例如下：

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="获取用户列表",
 *     @OA\Response(
 *         response=200,
 *         description="成功返回用户列表",
 *         @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/User"))
 *     ),
 *     @OA\Response(response=401, description="未授权访问")
 * )
 */
public function index()
{
    // 你的业务逻辑
}

如果需要定义数据模型，可以在模型类中添加注释：

/**
 * @OA\Schema(
 *     schema="User",
 *     title="用户模型",
 *     @OA\Property(property="id", type="integer", description="用户ID"),
 *     @OA\Property(property="name", type="string", description="用户名"),
 *     @OA\Property(property="email", type="string", description="邮箱")
 * )
 */
class User extends Model
{
    // 模型定义
}

3. 生成OpenAPI文档文件 #

在项目根目录创建一个生成脚本swagger-generate.php，内容如下：

<?php
require __DIR__ . '/vendor/autoload.php';

// 指定要扫描的控制器目录
$openapi = \OpenApi\Generator::scan([__DIR__ . '/app/Http/Controllers']);
// 生成JSON格式的文档并保存到public目录
file_put_contents(__DIR__ . '/public/swagger.json', $openapi->toJson(JSON_PRETTY_PRINT));

执行脚本生成文档：

php swagger-generate.php

执行完成后，public目录下会生成swagger.json文件，这就是你的API规范文档。

4. 部署并集成Swagger Editor #

1. 下载Swagger Editor的静态资源包，解压后将dist目录下的所有文件复制到Lumen项目的public/swagger-editor目录中。
2. 修改public/swagger-editor/config/defaults.json中的url字段为../swagger.json，让编辑器默认加载我们生成的文档。
3. 在bootstrap/app.php中添加访问路由：

$app->get('/swagger-editor', function () {
    return file_get_contents(public_path('swagger-editor/index.html'));
});

现在访问http://你的项目域名/swagger-editor，就能打开Swagger Editor，直接查看、编辑你的API文档。

5. 优化：自动生成文档（可选） #

为了避免每次修改注释后手动执行脚本，可以在composer.json中添加自定义脚本：

"scripts": {
    "swagger:generate": "php swagger-generate.php"
}

之后只需执行composer swagger:generate就能快速更新API文档。

注意事项 #

• 确保注释严格遵循OpenAPI 3.0规范，否则可能无法正确生成文档。
• 如果你的API有路由前缀，注释中的path字段要和实际路由保持一致。
• 若需要对Swagger Editor添加访问权限，可以在路由中添加Lumen的认证中间件。

内容的提问来源于stack exchange，提问作者rajesh sood