api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。

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()

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

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

c）、设置路由

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

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

d）、测试访问

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

三、使用

GET方法

1. /**  
2.  * @OA\Get( 
3.  *     tags={"数据管理"}, 
4.  *     summary="数据查询", 
5.  *     path="/api/data/search", 
6.  *     @OA\Response(response="200", description="Display a listing of projects."), 
7.  *     @OA\Parameter( 
8.  *         description="数据名称", 
9.  *         in="query", 
10.  *         name="name", 
11.  *         required=false, 
12.  *         @OA\Schema(type="string"), 
13.  *     ), 
14.  *     @OA\Parameter( 
15.  *         description="状态", 
16.  *         in="query", 
17.  *         name="status", 
18.  *         required=false, 
19.  *         @OA\Schema(type="integer"), 
20.  *     ), 
21.  *     @OA\Parameter( 
22.  *         description="每页记录数", 
23.  *         in="query", 
24.  *         name="page-size", 
25.  *         required=false, 
26.  *         @OA\Schema(type="integer"), 
27.  *     ), 
28.  *     @OA\Parameter( 
29.  *         description="当前页码", 
30.  *         in="query", 
31.  *         name="current-page", 
32.  *         required=false, 
33.  *         @OA\Schema(type="integer"), 
34.  *     ), 
35.  * ) 
36.  */ 

这里面:

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

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

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

POST方法

1. /**  
2.  * @OA\Post( 
3.  *     tags={"数据管理"}, 
4.  *     summary="添加数据", 
5.  *     path="/api/data", 
6.  *     @OA\Response(response="200", description="Display a listing of projects."), 
7.  *     @OA\RequestBody( 
8.  *         @OA\MediaType( 
9.  *             mediaType="x-www-form-urlencoded", 
10.  *             @OA\Schema( 
11.  *                 ref="#/components/schemas/DataModel", 
12.  *             ), 
13.  *         ), 
14.  *     ), 
15.  * ) 
16.  */ 

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

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

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

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

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

这里也可以单独写：

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

上面这样，有多少个参数就写多少个@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，内容大概如下：

1. window.onload = function() { 
2.   //<editor-fold desc="Changeable Configuration Block"> 
3.   // the following lines will be replaced by docker/configurator, when it runs in a docker-container 
4.   window.ui = SwaggerUIBundle({ 
5.     url: "/api/swagger/json", 
6.     dom_id: '#swagger-ui', 
7.     deepLinking: true, 
8.     presets: [ 
9.       SwaggerUIBundle.presets.apis, 
10.       SwaggerUIStandalonePreset 
11.     ], 
12.     plugins: [ 
13.       SwaggerUIBundle.plugins.DownloadUrl 
14.     ], 
15.     layout: "StandaloneLayout" 
16.   }); 
17.   //</editor-fold> 
18. }; 

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

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

Tags: Swagger PHP生成API文档

分享到：