TRR · v0.0.2 · 生成API文档篇

# 生成API文档篇

# API文档演示

• Html 格式： 👉 点我了解 👈
• Markdown 格式： 👉 点我了解 👈

# 使用教程

# composer 安装

composer require wangyu/tp-anntation

# 注册TP think 命令

注册命令

<?php
return [
"lin-cms:apiDoc" => \WangYu\annotation\DocCommand::class
];

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

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

反射标识说明：

例如：

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

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

反射标识说明：

/**
 * @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 --module=api  --type=html
  

  1
  
  • 输出

    Successful. Output Document Successful . File Path ：api-doc.html
  

  1
  
  • 查看 trr:doc 命令帮助

    php think trr:doc -h
  

  1
  
  • 输出

    wy@aokodeiMac TRR (fix/apidoc) $ php think trr:doc -h
    Usage:
      doc:build [options]
    
    Options:
          --module=MODULE   your API Folder,Examples: api = /application/api [default: "api"]
          --type=TYPE       your API file type,type = html or markdown [default: "html"]
          --name=NAME       your API to markdown filename [default: "api-md"]
          --force=FORCE     your API markdown filename is exist, backup and create, force = true or false [default: true]
      -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
  16
  

# 生成 Markdown 格式的 API 文档

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

php think trr:doc --module=api  --type=markdown

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

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

# 生成 HTML 格式的 API 文档(推荐)

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

php think trr:doc --module=api  --type=html

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

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