# 安装教程

# composer 安装

composer require wangyu/tp-anntation

# 使用教程

# 第一种：输出反射API文档

# 写 接口类 注释,例如：Admin 类

反射标识说明：

例如：

 /**
 * @doc('Admin 后台管理类')
 * @package app\api\controller\cms
 */
 class Admin
 {

# 写接口方法注释,例如：getAdminUsers 方法

注： 本扩展输出文档参数表是 markdown table 做的， 因为 markdown table 的分隔符 | 与 thinkphp 5.1验证规则分隔符|冲突

本扩展输出文档时采取 # 代替 thinkphp5.1 验证规则分隔符 |

使用时：@param('id','用户ID','require|number')

输出时：@param('id','用户ID','require#number')

反射标识说明：

 /**
  * @doc('创建图书')
  * @route('','post')
  * @validate('CreateGroup')
  * @param('name','图书名称','require|graph|length:1,50')
  * @param('img','图书img','require|graph|length:1,16')
  * @success('{"code":200,"msg":"操作成功","data":[]}')
  * @error('{"code":400,"msg":"appSecret不能为空","data":[]}')
  * @return array
  */
 public function create(){#......}

# 输出API文档

• 命令行模式

  有关于怎么使用命令行模式参考下，thinkphp5.1官方文档 点我

  • 配置application/command.php文件

    <?php
    return [
        // API文档输出
        'trr:doc'=> WangYu\annotation\DocCommand::class
    ];
  

  1
  2
  3
  4
  5
  
  • 运行 trr:doc 命令

    php think trr:doc
  

  1
  
  • 输出

    Successful. Output Document Successful . File Path ：api-md-20190701141656.md
  

  1
  
  • 查看 trr:doc 命令帮助

    php think trr:doc -h
  

  1
  
  • 输出

    Usage:
      doc:build [<module>] [<filename>]
    
    Arguments:
      module                your API Folder,Examples: api = /application/api [default: "api"]
      filename              your API to markdown filename
      
    Options:
      -h, --help            Display this help message
      -V, --version         Display this console version
      -q, --quiet           Do not output any message
          --ansi            Force ANSI output
          --no-ansi         Disable ANSI output
      -n, --no-interaction  Do not ask any interactive question
      -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug  
  

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  

• 使用Doc类创建

  • 实例化Doc类

    $doc = new \WangYu\Doc('API接口模块','输出文件名称');
  

  1
  
  • execute 创建文档

    $doc->execute();
  

  1
  
  • 在项目根目录查看 输出文件名称.md

# 生成 markdown 格式的 API 文档

# 命令行生成

在项目根目录下打开 cmd 或 终端 输入以下命令

php think trr:build

效果如下，代表文档生成成功：

F:\project\open-source-object\Trr\2019-7-6\TRR [master ≡ +0 ~217 -0 !]
λ  php think trr:build
Successful. Output Document Successful . File Path ：api-md.md