我已经在Lumen微框架中构建了一些REST API,它工作得很好。现在,我希望将Swagger集成到其中,以便将来使用时可以很好地记录该API。有人这么做过吗?
发布于 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)
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的配置文件
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
每次更新文档时运行此命令
请参见:
发布于 2018-03-25 16:45:06
我真的很难学会如何使用它。在这里,我将分享我为使其正常工作所做的一些事情
在您的终端中运行以下命令:
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
文件,添加以下示例
/**
* @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"
* )
* )
*/
然后运行
php artisan swagger-lume:publish
然后运行
php artisan swagger-lume:generate
这将生成JSON,可以从localhost:8000或提供流明服务的任何端口访问该JSON
注意:在存储库中创建了一个问题后,我发现要访问它,您需要使用
php -S localhost:8000 public/index.php
由于php -S localhost:8000 public
的一些PHP路由问题
https://stackoverflow.com/questions/45211512
复制相似问题