接口文檔

在線接口文檔

PhalApi提供一些非常實用而又貼心的功能特性，其中最具特色的就是自動生成的在線可視化文檔。在線接口文檔主要分為兩大類，分別是：

• 在線接口列表文檔
• 在線接口詳情文檔

當客戶端不知道有哪些接口服務，或者需要查看某個接口服務的說明時，可借助此在線接口文檔。訪問在線接口列表文檔的URL是：

http://dev.phalapi.net/docs.php

打開后，便可看到類似下面這樣的在線接口文檔。

此在線文檔是實時生成的，可根據接口源代碼以及注釋自動生成。當有新增接口服務時，刷新后便可立即看到效果。通過在接口列表文檔，可點擊進入相應的接口詳情文檔頁面。

溫馨提示：如果打開在線文檔，未顯示任何接口服務，請確保服務環境是否已關閉PHP的opcache緩存。

代碼、注釋與接口文檔

PhalApi提供了自動生成的在線接口文檔，對于每一個接口服務，都有對應的在線接口詳情文檔。如默認接口服務Site.Index的在線接口詳情文檔為：

此在線接口詳情文檔，從上到下，依次說明如下。

接口服務名稱

接口服務名稱是指用于請求時的名稱，對應s參數（或service參數）。接口服務的中文名稱，為不帶任何注解的注釋，通常為接口類成員函數的第一行注釋。

class Site extends Api {/*** 默認接口服務*/public function index() {} }

接口說明

接口說明對應接口類成員函數的@desc注釋。

class Site extends Api {/*** 默認接口服務* @desc 默認接口服務，當未指定接口服務時執行此接口服務*/public function index() {} }

接口參數

接口參數是根據接口類配置的參數規則自動生成，即對應當前接口類getRules()方法中的返回。其中最后的“說明” 字段對應參數規則中的desc選項?？梢耘渲枚鄠€參數規則。此外，配置文件./config/app.php中的公共參數規則也會顯示在此接口參數里。

class Site extends Api {public function getRules() {return array('index' => array('username' => array('name' => 'username', 'default' => 'PHPer', ),),);} }

返回結果

返回結果對應接口類成員函數的@return注釋，可以有多組，格式為：@return 返回類型 返回字段 說明。

class Site extends Api {/*** 默認接口服務* @desc 默認接口服務，當未指定接口服務時執行此接口服務* @return string title 標題* @return string content 內容* @return string version 版本，格式：X.X.X* @return int time 當前時間戳*/public function index() {} }

接口返回示例

為了方便客戶端在未調用接口前也能了解接口的返回格式和示例，可以添加為每個接口服務添加相應的返回示例、同時，考慮到服務端維護的便易性，我們會對每個接口服務單獨使用一個文件來存放。默認情況下，返回示例文件存放在：

./src/view/docs/demos

文件名是：

接口服務名稱 + .json

例如：

./src/view/docs/demos/App.Site.Index.json

示例文件里可以放置返回給客戶端的示例。如：

{"ret": 200,"data": {"title": "Hello PhalApi","version": "2.7.0","time": 1558489902},"msg": "" }

最后，在線文檔的展示效果是：

注意！接口返回示例，需要PhalApi 2.7.0 及以上版本方可支持。

異常情況

異常情況對應@exception注釋，可以有多組，格式為：@exception 錯誤碼 錯誤描述信息。例如：

/*** @exception 400 非法請求，參數傳遞錯誤*/public function index() {

刷新后，可以看到新增的異常情況說明。

公共注釋

對于當前類的全部函數成員的公共@exception異常情況注釋和@return返回結果注釋，可在類注釋中統一放置。而對于多個類公共的@exception和@return```注釋，則可以在父類的類注釋中統一放置。

也就是說，通過把@exception注解和@return注解移到類注釋，可以添加全部函數成員都適用的注解。例如，ApiUser類的全部接口都返回code字段，且都返回400和500異常，則可以：

<?php namespace AppApi;use PhalApiApi;/*** @return int code 操作碼，0表示成功* @exception 400 參數傳遞錯誤* @exception 500 服務器內部錯誤*/class User extends Api {

這樣就不需要在每個函數成員的注釋中重復添加注解。此外，也可以在父類的注釋中進行添加。對于相同異常碼的@exception注解，子類的注釋會覆蓋父類的注釋，方法的注釋會覆蓋類的注釋；而對于相同的返回結果@return注釋，也一樣。

需要注意的是，注釋必須是緊挨在類的前面，而不能是在namespace前面，否則會導致注釋解析失敗。

通過在線接口文檔進行測試

在線接口文檔，不僅可以用來查看接口文檔，包括接口參數、返回字段和功能說明外，還可以在上面進行接口測試。這將會直接請求當前的接口。效果如下：

如何生成離線接口文檔？

上面在線的接口文檔，也可以一鍵生成離線版的HTML文檔，方便傳閱，離線查看。

當需要生成離線文檔時，可以在終端，執行以下命令：

phalapi$ php ./public/docs.php Usage:生成展開版： php ./public/docs.php expand 生成折疊版： php ./public/docs.php fold腳本執行完畢！離線文檔保存路徑為：/path/to/phalapi/public/docs

執行后，可以看到類似上面的提示和結果輸出。再查看生成的離線文檔，可以看到類似有：

phalapi$ tree ./public/docs ./public/docs ├── App.Examples_CURD.Delete.html ├── App.Examples_CURD.Get.html ├── App.Examples_CURD.GetList.html ├── App.Examples_CURD.Insert.html ├── App.Examples_CURD.Update.html ├── App.Examples_Upload.Go.html ├── App.Site.Index.html └── index.html

最后，可以在頁面訪問此離線版文檔，如訪問鏈接：

http://dev.phalapi.net/docs/index.html

也可以將此docs目錄打包，在本地打開訪問查看。

創作挑戰賽新人創作獎勵來咯，堅持創作打卡瓜分現金大獎

總結

以上是生活随笔為你收集整理的接口返回的类型是html页面_1.10 PhalApi 2.x 接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。