thinkphp結合swagger自動生成接口文檔，附案例使用

一、swagger安裝javascript

第一步：安裝swagger-ui前端

去這裏下載https://github.com/swagger-api/swagger-ui

下載完成以後，將文件夾放到你的網站根目錄上面，例如我是放在我wamp下面的www目錄。php

接着找到dist目錄, 打開index.html把其中的那一串url改爲本身的好比http://localhost/tp/public/swagger.jsonhtml

注意這個url就是後面swagger.json 的路徑；前端

若是你想支持中文在index.html中加上java

<script src='lang/translator.js' type='text/javascript'>

</script><script src='lang/zh-cn.js' type='text/javascript'></script>

而後打開URL輸入http://localhost/swagger-ui/dist/index.html就能夠看到前端界面了, 應該是沒內容的, 由於還沒生成swagger.json, 生成好以後你設置的URL就起了做用。swagger.json我是放在tp框架下的swagger-docs目錄中的，具體路徑看你本身，具體下面會提到，不要慌O(∩_∩)O~。laravel

第二步：安裝swagger-php後端

進入你的項目目錄執行以下命令：git

composer require zircote/swagger-php

提示安裝完成後會在你tp項目的vendor中生成一個zircote的組件文件夾，說明已經安裝插件成功了。github

第三步：生成swagger.json文件

方法一、直接在命令行中輸入： php D:\Program\www\tp\vendor\zircote\swagger-php\bin\swagger D:\Program\www\tp\application\app\controller\ -o D:\Program\www\tp\public

注意：第一個路徑是你安裝成功後組件的路徑；
第二個路徑是你想要生成這個目錄下全部用swagger方式註釋的php文件，把全部註釋生成api文檔；
第三個路徑是你存放生成swagger.json的路徑

方法二、編寫控制器方法生成swagger.json：web

若是咱們每次修改了api，還要手動執行第三步的代碼，有些繁瑣，那咱們就在控制器中寫一個方法，每次訪問swagger-ui的時候自動執行，而後跳轉到前臺swagger界面中。ajax

下面是控制器裏面的方法

$path = '../application'; //你想要哪一個文件夾下面的註釋生成對應的API文檔 $swagger = \Swagger\scan($path); //header('Content-Type: application/json'); //echo $swagger; $swagger_json_path = $path.'/swagger-docs/swagger.json'; $res = file_put_contents($swagger_path, $swagger); if ($res == true) { $this->redirect('http://localhost/swagger-ui/dist/index.html'); }

第四步：編寫swagger註釋

控制器的註釋寫法

/**
 * @SWG\Resource(
 *  basePath="http://skyapi.dev",
 *  resourcePath="/vps",
 *  @SWG\Api(
 *   path="/vps",
 *   @SWG\Operation(
 *    method="GET",
 *    type="array",
 *    summary="Fetch vps lists",
 *    nickname="vps/index",
 *    @SWG\Parameter(
 *     name="expand",
 *     description="Models to expand",
 *     paramType="query",
 *     type="string",
 *     defaultValue="vps,os_template"
 *    )
 *   )
 *  )
 * )
 */
class VpsController extends Controller
{
    // ...
}

這只是個簡單的實例具體的註釋寫法請本身百度

二、swagger註釋使用

參考這個（寫的比較全面）：https://learnku.com/laravel/t/7430/how-to-write-api-documents-based-on-swagger-php#747b67

還有這個：https://blog.csdn.net/dyt19941205/article/details/79025266

這個：https://www.jianshu.com/p/554cd3762ab1

結合上面這幾篇文章學習寫了一個藉口文檔，也就四個方法，基本須要的東西都有了，之後再寫文檔能夠照搬了

寫接口文檔真的很費時間，尤爲寫在php註釋裏，比較簡單的文檔可使用swagger提供的編輯工具，直接在上面修改json文件後導出使用就能夠了：http://editor.swagger.io/

下面給一個完整的接口註釋：

<?php namespace app\app\controller; use think\Controller; use think\Request; use think\Db; /** * @SWG\Swagger( * schemes={"http"}, * host="127.0.0.1", * basePath="/restudy/public/index.php/app/", * consumes={"multipart/form-data","X-Requested-With/XMLHttpRequest"}, * produces={"application/json"}, * @SWG\Info( * version="1.0", * title="個人測試學習api項目", * description="接口學習，目前只寫了一個Api類，把頂級欄目接口、二級欄目接口、文章列表接口、文章內容接口寫到了一塊兒" * ), * * @SWG\Tag( * name="Api", * description="新聞webapp四大接口", * ), * ) */

class Api extends Controller { /** *@SWG\Get(path="/api/gettopnav", tags={"Api"}, * summary="獲取頂級欄目列表", * description="獲取頂級欄目列表,返回欄目id，名稱，和是否啓用欄目", @SWG\Parameter( * description="ajax請求要加上X-Requested-With:XMLHttpRequest頭字段", * format="string", * in="header", * name="X-Requested-With", * required=true, * type="string", default="XMLHttpRequest", * * ), @SWG\Response(response="200", description="操做成功", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=200, * ), * @SWG\Property( * property="msg", * type="string", example="頂級欄目返回成功", * ), @SWG\Property( * property="data", * type="object", example="[{cate_id:5,cate_name:'欄目1',cate_ison:1},{cate_id:6,cate_name:'欄目2',cate_ison:0}]", * ), * * )), @SWG\Response(response="201", description="數據爲空", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=201, * ), * @SWG\Property( * property="msg", * type="string", example="數據爲空!", * ), * * )), @SWG\Response(response="400", description="非法請求,不是ajax請求", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=400, * ), * @SWG\Property( * property="msg", * type="string", example="非法請求", * ), * * )), * ) */

    //頂級欄目接口
    public function getTopnav(){ if(request()->isAjax()){ $data=Db::table('re_cate')->where('cate_pid',0)->field('cate_id,cate_name,cate_ison')->select(); if(!empty($data)){ return json(['code'=>200,'msg'=>'頂級欄目返回成功','data'=>$data]); }else{ return json(['code'=>201,'msg'=>'數據爲空！']); } }else{ return json(['code'=>400,'msg'=>'非法請求']); } } /** *@SWG\Post(path="/api/getsonnav", tags={"Api"}, * summary="獲取二級欄目列表", * description="根據欄目id獲取二級欄目列表,返回欄目id，名稱，和是否啓用欄目", @SWG\Parameter( * description="ajax請求要加上X-Requested-With:XMLHttpRequest頭字段", * format="string", * in="header", * name="X-Requested-With", * required=true, * type="string", default="XMLHttpRequest", * * ), * @SWG\Parameter(name="id",type="integer", required=true, in="formData", * description="頂級欄目id" * ), @SWG\Response(response="200", description="操做成功", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=200, * ), * @SWG\Property( * property="msg", * type="string", example="二級欄目返回成功", * ), @SWG\Property( * property="data", * type="object", example="[{cate_id:5,cate_name:'欄目1',cate_ison:1},{cate_id:6,cate_name:'欄目2',cate_ison:0}]", * ), * * )), @SWG\Response(response="201", description="數據爲空", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=201, * ), * @SWG\Property( * property="msg", * type="string", example="數據爲空!", * ), * * )), @SWG\Response(response="400", description="非法請求,不是ajax請求", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=400, * ), * @SWG\Property( * property="msg", * type="string", example="非法請求", * ), * * )), * ) */

    //二級欄目接口
    public function getSonnav(){ if(request()->isAjax()){ $cate_id=input('id'); $data=Db::table('re_cate')->where('cate_pid',$cate_id)->field('cate_id,cate_name,cate_ison')->select(); if(!empty($data)){ return json(['code'=>200,'msg'=>'二級欄目返回成功','data'=>$data]); }else{ return json(['code'=>201,'msg'=>'無二級欄目']); } }else{ return json(['code'=>400,'msg'=>'非法請求']); } } /** *@SWG\Post(path="/api/getarticlelist", tags={"Api"}, * summary="獲取文章列表", * description="根據欄目id獲取文章列表（須要參數：欄目id，頁碼，一頁顯示文章數量）", @SWG\Parameter( * description="ajax請求要加上X-Requested-With:XMLHttpRequest頭字段", * format="string", * in="header", * name="X-Requested-With", * required=true, * type="string", default="XMLHttpRequest", * * ), * @SWG\Parameter(name="id",type="integer", required=true, in="formData", * description="欄目id" * ), @SWG\Parameter(name="p",type="integer", required=true, in="formData", * description="頁碼" * ), @SWG\Parameter(name="num",type="integer", required=true, in="formData", * description="每頁文章數量" * ), @SWG\Response(response="200", description="操做成功", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=200, * ), * @SWG\Property( * property="msg", * type="string", example="文章列表返回成功", * ), @SWG\Property( * property="data", * type="object", example="{total:null,per_page:5,current_page:1,last_page:null,data:[{ar_id:1,cate_id:10,ar_title:'文章標題一',ar_keywords:'文章關鍵字',ar_pic:'url',ar_content:'文章內容',ar_ison:1}]}", * ), * * )), @SWG\Response(response="201", description="數據爲空", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=201, * ), * @SWG\Property( * property="msg", * type="string", example="數據爲空!", * ), * * )), @SWG\Response(response="400", description="非法請求,不是ajax請求", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=400, * ), * @SWG\Property( * property="msg", * type="string", example="非法請求", * ), * * )), * ) */
    //指定欄目文章列表（須要參數：欄目id，頁碼，一頁顯示文章數量）
    /* 返回json格式 { "code": 200, "msg": "文章返回成功", "data": { "total": null, "per_page": "1", "current_page": 1, "last_page": null, "data": [ { "ar_id": 1, "cate_id": 10, "ar_title": "title", "ar_keywords": "k,e,y", "ar_pic": "public/static/uploads/20190902\\98edeb3d27fe4342da8b07d5ae3e98de.jpg", "ar_content": "<p>內容<br/></p>", "ar_ison": 1 } ] } } */
    public function getArticlelist(){ if(request()->isAjax()){ $cate_id=input('id'); $page=input('p'); $number=input('num'); $data=Db::table('re_article')->where('cate_id',$cate_id)->paginate($number,true,['page'=>$page]); if(!empty($data)){ return json(['code'=>200,'msg'=>'文章返回成功','data'=>$data]); }else{ return json(['code'=>201,'msg'=>'沒有數據了']); } }else{ return json(['code'=>400,'msg'=>'非法請求']); } } /** *@SWG\Post(path="/api/getarticlecontent", tags={"Api"}, * summary="獲取文章內容", * description="根據文章id獲取文章信息", @SWG\Parameter( * description="ajax請求要加上X-Requested-With:XMLHttpRequest頭字段", * format="string", * in="header", * name="X-Requested-With", * required=true, * type="string", default="XMLHttpRequest", * * ), * @SWG\Parameter(name="id",type="integer", required=true, in="formData", * description="文章id" * ), @SWG\Response(response="200", description="操做成功", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=200, * ), * @SWG\Property( * property="msg", * type="string", example="文章返回成功", * ), @SWG\Property( * property="data", * type="object", example="{ar_id:1,ar_title:'文章1',ar_pic:'url',ar_keywords:'文章關鍵字',ar_content:'文章內容',ar_ison:1}", * ), * * )), @SWG\Response(response="201", description="數據爲空", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=201, * ), * @SWG\Property( * property="msg", * type="string", example="數據爲空!", * ), * * )), @SWG\Response(response="400", description="非法請求,不是ajax請求", @SWG\Schema( * required={""}, * @SWG\Property( * property="code", * type="integer", example=400, * ), * @SWG\Property( * property="msg", * type="string", example="非法請求", * ), * * )), * ) */
    //獲取指定文章內容
     public function getArticlecontent(){ if(request()->isAjax()){ $ar_id=input('id'); $data=Db::table('re_article')->where('ar_id',$ar_id)->find(); if(!empty($data)){ return json(['code'=>200,'msg'=>'文章返回成功','data'=>$data]); }else{ return json(['code'=>201,'msg'=>'無此文章']); } }else{ return json(['code'=>400,'msg'=>'非法請求']); } } }