lxlxw/api-doc

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

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

This package is not auto-updated.

Last update: 2024-11-13 21:07:53 UTC


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();

配置

  • 配置列表

展示

  • markdown(default)

  • html

  • 自定义模版

计划

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