lxlxw/api-doc

根据注释生成markdown或html形式的接口文档

dev-master 2017-03-27 08:15 UTC

MIT

• lxlxw

README

根据注释生成markdown或html形式的API接口文档插件

• 描述/说明
• 环境
• 安装
• 示例
• 配置
• 展示
• 计划

描述/说明

• 可以根据api类/方法的注释可以生成markdown或html形式的API接口文档。

• 模版默认为markdown，亦可自定义模版。

• 依赖于composer管理。

• 该插件未经过严格的测试，建议只部署在本地或测试环境使用。

环境

• PHP >= 5.4 或以上

• composer依赖

安装

• 添加下面一行到你项目的composer.json中。

{
    "require": {
        ...
        "lxlxw/api-doc": "dev-master"
    }
}

• 更新vendor包

$ php composer.phar update

示例

• 要生成注释的接口类/方法 #testController.php

<?php 
/**
 * @author lxw
 * @group(name="test", description="test")
 */

class Doc {
    
    function __construct() {
        parent::__construct();
    }

    /**
     * @ApiDescription(这是接口的描述)
     * @ApiMethod(post)
     * @ApiUrl(192.168.0.1:80/doc/test)
     * @ApiNotice(这是接口的说明)
     * @ApiSuccess(value="{'firstname' : 'lxw', 'lastname'  : 'lxlxw', 'lastLogin' : '2016-11-11'}")
     * @ApiExample(value="{'username':'lxw','password':'123456'}")
     * @ApiParams(name="id", type="integer", is_selected=true, description="User id")
     * @ApiParams(name="sort", type="enum[asc,desc]", description="User data")
     * @ApiReturn(name="id", type="integer", description="User id")
     * @ApiReturn(name="sort", type="enum[asc,desc]", description="sort data")
     * @ApiReturn(name="page", type="integer", description="data of page")
     * @ApiReturn(name="count", type="integer", description="data of page")
     */
    function test(){
        echo 'hello';
    }
}

• 生成文档处理程序 #apidoc.php

<?php

require 'vendor/autoload.php';

$obj = new ApiDoc\ApiDoc();

//直接生成文档，采用程序默认配置
//$obj->build();

//根据配置的参数生成文档
$config = [
            'build_path' => __DIR__,
            'vender_path' => __DIR__ . "/../vender/",
            'template' => 'default',
            'template_ext' => '.md'
          ];
$obj->set($config)->build();

配置

• 配置列表

字段	说明	例子
allowed_file	生成注释文档的文件后缀名称	如: .php, .js 等
build_path	生成注释文档的文件所在目录	如: DIR."/controllers" , 程序会自行遍历该目录下的文件
vender_path	生成文档的存放目录	如: DIR."/save/" , 程序会将生成好的文档存放至该目录
template_ext	生成文档的后缀名称	如: .md, .html 等
template	生成文档所使用的模版	暂提供 default[markdown], html, wiki模版，亦可自定义模版

展示

• markdown(default)

• html

• 自定义模版

计划

• 完善通用模版，如有更改模版欢迎Pull requests给我。
• 编写后台管理界面，用于填写配置项并生成api文档。