Swagger PHP

Swagger PHP

PHP使用Swagger生成好看的API文档不是不可能,而是非常简单。

首先本人使用Laravel框架,所以在Laravel上安装swagger-php。

一、安装swagger – php

composer require zircote/swagger-php

swagger-php提供了命令行工具,所以可以全局安装,然后把工具的路径加到PATH里去。

composer global require zircote/swagger-php

然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到,就不研究了。

二、设置一个输出api文档数据的接口

a)、生成一个控制器: SwaggerController

b)、添加一个方法: getJSON()

    public function getJSON()
{
$swagger = \OpenApi\Generator::scan([app_path('Http/Controllers/')]);
return response()->json($swagger, 200);
}

有的文章里写 \Swagger\scan(),但我这里报错,说找不到这个类。查了官方文档,要用 \OpenApi\Generator::scan()。有可能是新版本做了修改。

c)、设置路由

api.php 或者 web.php都行,路径不同而已。本人选择api.php。所以访问路径要加个前缀:/api。

Route::group(['prefix' => 'swagger'], function () {
Route::get('json', [\App\Http\Controllers\SwaggerController::class, 'getJSON']);
});

d)、测试访问

访问 http://localhost:8000/api/swagger/json 如果看到页面正常输出json,说明配置成功了。不然就按错误提示一项项去修改吧。

三、使用

GET方法

    /**
* @OA\Get(
*     tags={"数据管理"},
*     summary="数据查询",
*     path="/api/data/search",
*     @OA\Response(response="200", description="Display a listing of projects."),
*     @OA\Parameter(
*         description="数据名称",
*         in="query",
*         name="name",
*         required=false,
*         @OA\Schema(type="string"),
*     ),
*     @OA\Parameter(
*         description="状态",
*         in="query",
*         name="status",
*         required=false,
*         @OA\Schema(type="integer"),
*     ),
*     @OA\Parameter(
*         description="每页记录数",
*         in="query",
*         name="page-size",
*         required=false,
*         @OA\Schema(type="integer"),
*     ),
*     @OA\Parameter(
*         description="当前页码",
*         in="query",
*         name="current-page",
*         required=false,
*         @OA\Schema(type="integer"),
*     ),
* )
*/

这里面:

in 表示该参数出现在哪里。 query的话就是用&拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里;cookie 自然是放在cookie里。

这个版本里formData, body这些都没有了。

required 看名字就知道 true是必填项,false是选填项。

POST方法

    /**
* @OA\Post(
*     tags={"数据管理"},
*     summary="添加数据",
*     path="/api/data",
*     @OA\Response(response="200", description="Display a listing of projects."),
*     @OA\RequestBody(
*         @OA\MediaType(
*             mediaType="x-www-form-urlencoded",
*             @OA\Schema(
*                 ref="#/components/schemas/DataModel",
*             ),
*         ),
*     ),
* )
*/

因为本人的前端代码post都是表单提交,所以这里的post方法要用@OA\RequestBody。

@OA\Parameter是参数,是可以放到url上,但是post的表单提交,数据是不出现在url上的。

@OA\MediaType 这个: x-www-form-urlencoded 表单提交;application/json 提交json格式的数据;multipart/form-data 文件上传;

     *             @OA\Schema(
*                 ref="#/components/schemas/DataModel",
*             ),

这个是关联到一个已经定义好的schema上,省得使用相同数据的每个接口注释里都写一遍。

这里也可以单独写:

 * @OA\Schema(
*   required={"name", "code"},
*   @OA\Property(property="name", type="string", title="姓名", description="这是姓名"),
*   @OA\Property(property="code", type="string", title="代码", description="这是代码"),
*   @OA\Property(property="phone", type="string", title="电话", description="这是电话"),
* ),

上面这样,有多少个参数就写多少个@OA\Property。

这里的required是个数组,写在里面的都是必填项。

其它方法都差不多,以后有用到了再记录。

四、显示swagger ui

下载swagger ui的代码: https://github.com/swagger-api/swagger-ui/releases

解压后,把目录里的dist目录,复制到laravel的public目录下面,改名为swagger-ui。文件名随便取,不冲突就行。

找开这个swagger-ui目录下的swagger-initializer.js,内容大概如下:

window.onload = function() {
//<editor-fold desc="Changeable Configuration Block">
// the following lines will be replaced by docker/configurator, when it runs in a docker-container
window.ui = SwaggerUIBundle({
url: "/api/swagger/json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});
//</editor-fold>
};

主要是改 url这项。改成前面设的路由地址。这里是 "/api/swagger/json"。

完成后访问 http://localhost:8000/swagger-ui/ 就能看到swagger形成的api文档了。

-完-

                       

点击阅读全文

上一篇 2023年 6月 9日 pm9:02
下一篇 2023年 6月 9日 pm9:02