如何在Lumen/Laravel中为REST API集成Swagger? [英] How to integrate Swagger in Lumen/Laravel for REST API?
问题描述
我已经在Lumen微型框架中构建了一些REST API,并且运行良好.现在,我想将Swagger集成到其中,以便将来使用时可以很好地记录该API.有人做过吗?
I have built some REST API in Lumen micro framework and it's working fine. Now I want to integrate Swagger into it so the API will be well documented on future use. Has anyone done this?
推荐答案
Laravel Lumen 5.7 (
Steps to follow for Laravel Lumen 5.7 with swagger using OpenApi 3.0 specs (this governs the way you write annotations so that swagger documentation is generated)
为了使它起作用,我在@ black-mamba答案上进行了此调整.
I reached this adjusting on @black-mamba answer in order to make it work.
1.安装swagger-lume依赖项(也将安装swagger)
composer require "darkaonline/swagger-lume:5.6.*"
2.编辑bootstrap/app.php
文件
2. Edit bootstrap/app.php
file
确保未注释
$app->withFacades();
(在第26行附近)
make sure
$app->withFacades();
is NOT commented (around line 26)
在注册容器绑定部分
$app->configure('swagger-lume');
在注册服务提供商部分的
添加
in Register Service Providers section add
$app->register(\SwaggerLume\ServiceProvider::class);
3.发布有关摇头灯的配置文件
php artisan swagger-lume:publish
4.在代码中添加注释
例如,在您的app/Http/Controllers/Controller.php
中,您可以拥有文档的常规部分
For example in your app/Http/Controllers/Controller.php
you could have the general part of the documentation
<?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"
* )
* )
*/
}
在每个控制器内部,每个公共方法上方都应具有适当的注释
And inside each of your controllers you should have the appropriate annotations above each public method
<?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
每次更新文档时都要运行
Run this each time you update the documentation
请参阅:
- http://zircote.com/swagger-php/Getting-started.html
- https://github.com/DarkaOnLine/SwaggerLume
- https://swagger.io/specification/
- http://zircote.com/swagger-php/Getting-started.html
- https://github.com/DarkaOnLine/SwaggerLume
- https://swagger.io/specification/
这篇关于如何在Lumen/Laravel中为REST API集成Swagger?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!