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

Posted 2023-02-16

技术标签:

【中文标题】如何在 Lumen/Laravel 中为 REST API 集成 Swagger？【英文标题】：How to integrate Swagger in Lumen/Laravel for REST API? 【发布时间】：2017-12-25 23:05:19 【问题描述】：

我在 Lumen 微框架中构建了一些 REST API，它运行良好。现在我想将 Swagger 集成到其中，这样 API 将在未来使用时得到很好的记录。有人做过吗？

【问题讨论】：

这可能很有趣：github.com/DarkaOnLine/SwaggerLume @KimberlyW：我已经集成了这个但是如何使用它？您需要添加如下链接所示的 swagger cmets，并按照 SwaggerLume 的文档生成实际的 Swagger html 页面。 github.com/zircote/swagger-php @AnandPandey 我列出了 Lumen 创建的所有端点，并在 /api/documentation 路径上找到了 Swagger UI 网页，在 /docs 路径上找到了 Swagger json。我在文档中没有找到任何内容。这篇文章对每一位初学者都有帮助phparticles.com/laravel/… 【参考方案1】：

使用 OpenApi 3.0 规范的 Laravel Lumen 5.7 和 swagger 遵循的步骤（这控制了您编写注释的方式，以便生成 swagger 文档）

这些步骤是不久前编写的，但它们仍然适用于 Laravel Lumen 6.X、7.X 和 8.X

我在@black-mamba 答案上进行了调整以使其正常工作。

1.安装 swagger-lume 依赖项（也安装 swagger）

composer require "darkaonline/swagger-lume:5.6.*"

2。编辑bootstrap/app.php文件

确保$app->withFacades(); 没有被注释（大约第 26 行）

在创建应用程序部分在注册容器绑定部分之前添加以下内容
$app->configure('swagger-lume');
在注册服务提供商部分添加
$app->register(\SwaggerLume\ServiceProvider::class);

3.发布 swagger-lume 的配置文件

php artisan swagger-lume:publish

4.为您的代码添加注释

例如，在您的 app/Http/Controllers/Controller.php 中，您可以拥有文档的一般部分

<?php

namespace App\Http\Controllers;

use Laravel\Lumen\Routing\Controller as BaseController;

class Controller extends BaseController

    /**
     * @OA\Info(
     *   title="Example API",
     *   version="1.0",
     *   @OA\Contact(
     *     email="support@example.com",
     *     name="Support Team"
     *   )
     * )
     */

在您的每个控制器内部，您应该在每个公共方法上方都有适当的注释

<?php

namespace App\Http\Controllers;

class ExampleController extends Controller

    /**
     * @OA\Get(
     *     path="/sample/category/things",
     *     operationId="/sample/category/things",
     *     tags="yourtag",
     *     @OA\Parameter(
     *         name="category",
     *         in="path",
     *         description="The category parameter in path",
     *         required=true,
     *         @OA\Schema(type="string")
     *     ),
     *     @OA\Parameter(
     *         name="criteria",
     *         in="query",
     *         description="Some optional other parameter",
     *         required=false,
     *         @OA\Schema(type="string")
     *     ),
     *     @OA\Response(
     *         response="200",
     *         description="Returns some sample category things",
     *         @OA\JsonContent()
     *     ),
     *     @OA\Response(
     *         response="400",
     *         description="Error: Bad request. When required parameters were not supplied.",
     *     ),
     * )
     */
    public function getThings(Request $request, $category)
    
        $criteria= $request->input("criteria");
        if (! isset($category)) 
            return response()->json(null, Response::HTTP_BAD_REQUEST);
        
        
        // ...
        
        return response()->json(["thing1", "thing2"], Response::HTTP_OK);

5.生成 swagger 文档

php artisan swagger-lume:generate

每次更新文档时运行它

见：

https://zircote.github.io/swagger-php/ https://github.com/DarkaOnLine/SwaggerLume https://swagger.io/specification/

【讨论】：

有什么办法让它自动生成注释？？？就像我们在 .net core 和 django 中所拥有的一样，您不需要使用注释 @Farshad 是的，在 config/swagger-lume.php "SWAGGER_GENERATE_ALWAYS" 并给它值 'true' 就像这个例子 'generate_always' => env('SWAGGER_GENERATE_ALWAYS', true),跨度> 最后访问 swagger json 在本地使用[yourlocalhost]/docs，对于 ui 本地使用[yourlocalhost]/api/documentation。如果您的 UI 缺少资产，请查看此链接 link。【参考方案2】：

我很难学会如何使用它。在这里，我将分享我为使其正常工作所做的一些事情

Use this wrapper

在终端中运行此命令：

composer require "darkaonline/swagger-lume:5.5.*"

如果这对您不起作用，则来自链接的 repo 中的旧版本

然后从 repo 执行以下步骤：

打开您的 bootstrap/app.php 文件并：在创建应用程序中取消注释此行（第 26 行附近）部分：
 $app->withFacades(); add this line before Register Container Bindings section:

 $app->configure('swagger-lume'); add this line in Register Service Providers section:

$app->register(\SwaggerLume\ServiceProvider::class);

然后你需要为你的项目使用注解而不是 YAML 或 JSON For more 在您的应用文件夹中创建一个Annotation.php 文件添加以下示例

/**
 * @SWG\Swagger(
 *     basePath="/",
 *     schemes="http",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="HAVE MY BOOKS",
 *         @SWG\Contact(
 *             email="example@test.com"
 *         ),
 *     )
 * )
 */
/**
* @SWG\Get(
 *   path="/",
 *   summary="Version",
 *   @SWG\Response(
 *     response=200,
 *     description="Working"
 *   ),
 *   @SWG\Response(
 *     response="default",
 *     description="an ""unexpected"" error"
 *   )
 * )
 */

然后运行