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

问题描述

我已经在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 ()使用 OpenApi 3.0 规范进行操作的步骤(这决定了您的方式编写注释，以便生成草率的文档)

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->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="[e-mail]",
     *     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?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！