用開源 apidoc rap編寫php接口文檔

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目錄