首页
学习
活动
专区
工具
TVP
发布
社区首页 >问答首页 >如何在Lumen/Laravel for REST API中集成Swagger?

如何在Lumen/Laravel for REST API中集成Swagger?
EN

Stack Overflow用户
提问于 2017-07-20 18:02:28
回答 2查看 17.2K关注 0票数 14

我已经在Lumen微框架中构建了一些REST API,它工作得很好。现在,我希望将Swagger集成到其中,以便将来使用时可以很好地记录该API。有人这么做过吗?

EN

回答 2

Stack Overflow用户

发布于 2018-10-18 20:03:34

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

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

为了让它正常工作,我在@black-mamba上做了这样的调整。

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

代码语言:javascript
复制
composer require "darkaonline/swagger-lume:5.6.*"

文件2.编辑bootstrap/app.php

确保$app->withFacades();未被注释(在第26行附近)

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

$app->configure('swagger-lume');

在注册服务提供者部分中添加

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

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

代码语言:javascript
复制
php artisan swagger-lume:publish

4.向代码添加批注

例如,在您的app/Http/Controllers/Controller.php中,您可以使用文档的一般部分

代码语言:javascript
复制
<?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"
     *   )
     * )
     */
}

在每个控制器中,每个公共方法的上方都应该有适当的注释

代码语言:javascript
复制
<?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文档

代码语言:javascript
复制
php artisan swagger-lume:generate

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

请参见:

票数 16
EN

Stack Overflow用户

发布于 2018-03-25 16:45:06

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

Use this wrapper

在您的终端中运行以下命令:

代码语言:javascript
复制
composer require "darkaonline/swagger-lume:5.5.*"

或来自repo链接的旧版本,如果这对您不起作用

然后从repo中执行以下步骤:

打开您的bootstrap/app.php文件,并在创建应用程序部分中取消注释此行(在第26行附近):

$app->withFacades();在注册容器绑定部分之前添加此行:$app->configure('swagger-lume');在注册服务提供者部分添加此行:$app->register(\SwaggerLume\ServiceProvider::class);

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

代码语言:javascript
复制
/**
 * @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"
 *   )
 * )
 */

然后运行

代码语言:javascript
复制
php artisan swagger-lume:publish

然后运行

代码语言:javascript
复制
php artisan swagger-lume:generate

这将生成JSON,可以从localhost:8000或提供流明服务的任何端口访问该JSON

注意:在存储库中创建了一个问题后,我发现要访问它,您需要使用

代码语言:javascript
复制
php -S localhost:8000 public/index.php

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

票数 9
EN
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://stackoverflow.com/questions/45211512

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档