从0到1教你在tp6中集成swagger-php来自动生成文档

写文档是程序员恼火的事情，如果能自动生成文档那就好了，这里介绍了swagger-php 自动生成文档，废话不多说，我们直接开始。网上的一些教程都是老掉牙的，非常影响我们的实际操作，建议搭建看我这篇教程。

大致步骤如下
1：安装swagger-php 
2：安装swagger-ui
3：配置接口地址,添加备注
4：修改ui文件

好了我们来详细讲解一下吧。
1：安装swagger-php

composer require zircote/swagger-php

这里会安装最新的3.*版本

2：安装ui文件

分享链接：http://pan.micuer.com/#s/7DKEbijw
访问密码：micuer.com

3:添加备注

```
<?php

namespace app\api\controller;

use app\common\controller\Api;
use app\common\model\PileOrder;

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
class ChargePile extends Api
{
    protected $noNeedLogin = ['*'];
    protected $noNeedRight = ['*'];

/**
     * 根据uid或unionid，查询用户预约充电桩的状态列表
     * @desc  根据uid或unionid，查询用户预约充电桩的状态列表，暂不用此函数
     * @param string uid
     * @param string unionid
     * @return array|string
     */

/**
     * @OA\Get(
     *   path="/queryCarList",
     *   summary="根据uid或unionid，查询用户预约充电桩的状态列表",
     *   @OA\Response(
     *     response=200,
     *     description="根据uid或unionid，查询用户预约充电桩的状态列表"
     *   ),
     *   @OA\Response(
     *     response="default",
     *     description="an ""unexpected"" error"
     *   )
     * )
     */
    public function queryCarList(){
        $uid = $this->request->param("uid","","trim,intval");
        $unionid = $this->request->param("unionid","","trim");
        $mod = new PileOrder();
        if(!$uid && !$unionid){
            return json(["ret"=>304,"msg"=>"参数错误","data"=>[]]);
        }

if($uid) {
            $list = $mod
                ->where("uid",$uid)
                ->order("t_update_time DESC")
                ->select();
        }

if($unionid){
            $list = $mod
                ->where("unionid",$unionid)
                ->order("t_update_time DESC")
                ->select();
        }

foreach ($list as $k => $v){
            $list[$k]["mobile"] =substr_replace($v["mobile"], '****', 3, 4);
        }

return json(["ret"=>200,"msg"=>"成功","data"=>$list]);
    }

}

```
4:修改UI文件

[![](https://micuu.com/data/upload/20210608/60bf168b5c801.png)](https://micuu.com/data/upload/20210608/60bf168b5c801.png)

[![](https://micuu.com/data/upload/20210608/60bf16c95a9a5.png)](https://micuu.com/data/upload/20210608/60bf16c95a9a5.png)

5：接口实现方法

public function index()
    {
        $openapi = \OpenApi\Generator::scan(['../application/api/controller']);
        header('Content-Type: application/x-yaml');
        echo $openapi->toYaml();
    }
	
注解方式参考：
https://www.sdk.cn/details/9pPQD6wqK09L8ozvNy

附：如果是命令行生成文档对应的文件

php ./vendor/bin/openapi ./app/controller -o ./public
注意-o前面的文件夹和后面的文件夹路径

在线视频教程
https://micuu.com/new/1650.html

附：一个简单的备注示例
```
    /**
     * @OA\Post (
     *   path="/api/xxxx/createOrder",
     *   summary="创建xxx",
     *   description="根据用户uid或unionid，来创建预约安装充电桩。如果已经有记录（不管是否已安装还是未安装），都提示“已预约”",
     *   @OA\Parameter(name="uid",in="query",required=false,description="用户id"),
     *   @OA\Parameter(name="unionid",in="query",required=false,description="unionid"),
     *   @OA\Parameter(name="name",in="query",required=false,description="用户的name"),
     *   @OA\Parameter(name="n_realcar_id",in="query",required=false,description="车辆id"),
     *   @OA\Parameter(name="car_series",in="query",required=false,description="车系"),
     *   @OA\Parameter(name="vin_end_six",in="query",required=false,description="车架号后6位"),
     *   @OA\Parameter(name="vin",in="query",required=false,description="车架号vin码"),
     *   @OA\Parameter(name="mobile",in="query",required=false,description="手机号"),
     *   @OA\Parameter(name="province",in="query",required=false,description="省"),
     *   @OA\Parameter(name="city",in="query",required=false,description="市"),
     *   @OA\Parameter(name="address",in="query",required=false,description="详细地址"),
     *   @OA\Response(
     *     response=200,
     *     description="ture或者false"
     *   )
     * )
     */
```

注:原创不易,转载请注明出处( https://micuu.com/new/1648.html )，本站所有资源来源于网络收集，如有侵权请联系QQ245557979进行清除。