用開源 apidoc rap編寫php介面文件

航空母艦發表於2016-05-31
APIPHP

RAP是一個視覺化介面管理工具 通過分析介面結構，動態生成模擬資料，校驗真實介面正確性， 圍繞介面定義，通過一系列自動化工具提升我們的協作效率

 

生成一個REST風格的Web API文件。

安裝apidocjs

npm install apidoc -g

 

 生成文件必須有.json 檔案和.php檔案

[root@centos php]# ls
apidoc.json  test.php
{
    "name": "apidoc-例子",
    "version": "0.3.0",
    "description": "apiDoc example project",
    "title": "apidoc-使用者介面文件",
    "url": "https://[base_domain]/index.php",
    "order": [ 
        "getUser",
        "getList"
    ],
    "template": {
        "withCompare": true,
        "withGenerator": true
    }
}
<?php
/**
 * @apiDefine User 測試apiGroup名字
 */

/**
 * @api {get} ?m=content&c=api&a=user 得到使用者資訊
 *
 * @apiHeader {String} access-key Users unique access-key.
 *
 * @apiVersion 0.2.2
 *
 * @apiName getUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname 使用者的姓名.
 * @apiSuccess {array} item  Lastname of the User.
 *
 * @apiSuccessExample {json} Request-Json-Example:
 *   HTTP/1.1 200 OK
 *   {
 *    "business_code": "busc0000001",
 *    "item": [
 *       {
 *       "is_authorization": "1" //2 已開通 1 授權 0 沒有授權
 *       "type": "module" //module 業務 extends擴充套件
 *        }
 *     ]
 *   }
 */
 function find(){}
 ?>

然後直接執行命令apidoc, 然後會直接預設生成一個doc檔案目錄，當然可以指定一下（用i和o命令 即input和output）

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

整個目錄生成文件

apidoc -i /path -o /path1/doc

只會生成含有apidoc註釋的檔案，更新apidoc註釋後重新生成需要刪除doc目錄

 

相關文章