Laravel + swagger 生成API文档

Skiy 25天前 15

1. 安装插件

composer require darkaonline/l5-swagger


2. 配置插件

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"


3. 修改文件

  3.1 config/app.php 中的 providers 添加

        L5Swagger\L5SwaggerServiceProvider::class, // Swagger


  3.2 app/Http/Controller.php 的类定义的上部添加以下文档说明(可根据自己的信息修改)

/**

 * @SWG\Swagger(

 *     @OA\Info(title="XXX 接口说明文档", version="0.1")

 * )

 */

class Controller extends BaseController

   

   3.3 app/Http/AccountController.php 的 login 上部添加 (举个例子)

    /**

     * @OA\Post(

     *     path="/account/login",

     *     tags={"账号管理"},

     *     summary="账号登录",

     *     description="账号登录",

     *     operationId="TimeShow",

     *     deprecated=false,

     *     @OA\Parameter(

     *         name="access_token",

     *         in="query",

     *         description="用户授权",

     *         required=true,

     *         @OA\Schema(

     *             type="string"

     *         )

     *     ),

     *     @OA\Response(

     *         response=200,

     *         description="操作成功返回"

     *     ),

     *     @OA\Response(

     *         response=400,

     *         description="发生错误"

     *     )

     * )

     */

    public function login(Request $request)

 

4. 编译接口文档

php artisan l5-swagger:generate


5. 查看文档

YOUR_PROJECT.test//api/documentation (可修改 config/l5-swagger.php 中的 routes/api)


可能会报的错误:


1. 找不到 docs/asset/xxx.css 之类的:(缺少静态文件)

mkdir -p public/docs/asset && cp -r vendor/swagger-api/swagger-ui/dist/* public/docs/asset

(复制 vendor/swagger-api/swagger-ui/dist/ 到 public/docs/asset/ 下)


更多文档请查看:https://github.com/zircote/swagger-php

最新回复 (0)
返回
发新帖