用开源 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目录

用开源 apidoc rap编写php接口文档

猜你喜欢