Laravel 集成 Swagger 为 API 生成接口文档并对接口进行测试

安装扩展包

composer require "darkaonline/l5-swagger:5.8.*"

发布该扩展包的配置和视图文件:

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

.env 中设置 Laravel 项目 API 接口的 URL 根路径:

L5_SWAGGER_CONST_HOST=http://project.test/api

添加 OpenAPI 注解

参考文档

生成 API 文档

php artisan l5-swagger:generate

通过 Swagger UI 查看 & 访问 API

然后我们在浏览器中通过 http://project.test/api/documentation 访问 API 文档,就可以看到基于 Swagger UI 渲染的文档信息了
例子:https://petstore.swagger.io/#/

参考文档
https://xueyuanjun.com/post/19694

Swagger API接口例子

修改 InfoServer

/**
 * @OA\Info(
 *     version="1.0",
 *     title="项目 接口文档"
 * ),
 * @OA\Server(
 *     url="http://project.test/api"
 * )
 */
InfoServer的显示

登陆TOKEN方法

点击Authorize按钮,在Value里填值

GET方法

例:

/**
* @OA\Get(
*     path="/project/list",
*     operationId="getList",
*     tags={"项目"},
*     summary="项目列表",
*     description="项目列表",
*     @OA\Parameter(
*        name="Accept",
*        required=true,
*        in="header",
*        description="Accept 请求头",
*        @OA\Schema(
*           type="string",
*           default="application/json"
*        )
*     ),
*     @OA\Parameter(
*        name="id",
*        required=true,
*        in="query",
*        description="ID",
*        @OA\Schema(
*           type="integer",
*        )
*     ),
*     @OA\Response(
*         response=200,
*         description="id",
*     ),
*     security={
*         {"passport": {}},
*     }
* )
*/

POST方法

例:

/**
* @OA\Post(
*     path="/project/create",
*     operationId="getCreate",
*     tags={"项目"},
*     summary="创建项目",
*     description="新建项目",
*     @OA\Parameter(
*        name="Accept",
*        required=true,
*        in="header",
*        description="Accept 请求头",
*        @OA\Schema(
*           type="string",
*           default="application/json"
*        )
*     ),
*     @OA\Parameter(
*        name="title",
*        required=true,
*        in="query",
*        description="标题",
*        @OA\Schema(
*           type="string",
*        )
*     ),
*     @OA\Parameter(
*        name="company_id",
*        required=true,
*        in="query",
*        description="公司ID",
*        @OA\Schema(
*           type="integer",
*        )
*     ),
*     @OA\Parameter(
*        name="file",
*        required=false,
*        in="query",
*        description="文件",
*        @OA\Schema(
*           type="file",
*        )
*     ),
*     @OA\Response(
*         response=200,
*         description="用户信息",
*     ),
*     security={
*         {"passport": {}},
*     }
* )
*/

 4,568 total views,  2 views today

Revisions

There are no revisions for this post.

Comments are closed.