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

Question

我在Lumen微框架中构建了一些REST API,它工作正常.现在我想将Swagger集成到其中,以便API在未来的使用中得到很好的记录.有没有人这样做过？

Answer 1

Laravel Lumen 5.7的步骤,使用OpenApi 3.0规范的swagger (这决定了你编写注释的方式,以便生成swagger文档)

我调整了@ black-mamba的答案,以使其工作.

1.安装swagger-lume依赖项(也安装swagger)

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

2.编辑bootstrap/app.php文件

确保$app->withFacades();没有评论(第26行)

在Create The Application部分中,在Register Container Bindings部分之前添加以下内容

$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.生成昂首阔步的文档

php artisan swagger-lume:generate

每次更新文档时都运行此命令

看到:

• http://zircote.com/swagger-php/Getting-started.html
• https://github.com/DarkaOnLine/SwaggerLume
• https://swagger.io/specification/

Answer 2

我真的很难学习如何使用它。在这里，我将分享我为使之工作所做的一些事情

使用这个包装

在终端中运行以下命令：

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

或回购链接中的旧版本（如果此操作不适合您）

然后从仓库中执行以下步骤：

打开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。 有关更多信息Annotation.php，请在应用文件夹中 创建文件，并添加以下示例

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

然后跑

php artisan swagger-lume:publish

然后跑

php artisan swagger-lume:generate

这将生成可以从您的localhost：8000或您为LUMEN服务提供服务的任何端口访问的JSON

注意：在仓库中创建问题后，我发现要访问该目录，您需要使用

php -S localhost:8000 public/index.php

由于某些PHP路由问题 php -S localhost:8000 public