README

• Phpdoc — 文档以phpdoc注释的形式编写。从中生成.md文件。

• Slate docker — 生成的.md文件格式支持 slate

安装

composer require ruvents/annotation-md

使用

$controllersPath = PATH_TO_CONTROLLERS;
$buildPath = BUILD_PATH;

$params = [
            "title"     => "Заголовок",
            "baseUrl"   => "http://api.yoursite.com"
        ];

$parser = new Parser($controllersPath, $buildPath, $params);
$parser->parse();

• $controllersPath - 将要搜索控制器的文件夹路径。
• $buildPath - 将保存逐个.md文件的文件夹路径

注释

支持的注释

• ApiController — 描述控制器。文档中的章节。
• ApiContent — 随意内容块。在文档中表示为章节。
• ApiError — 描述错误的块。添加到文档末尾。
• ApiAction — 控制器动作。文档章节的子章节。
• Sample - 使用javascript、php、shell、ruby、python等语言中的一个的代码示例
• Request - 描述请求。
• Param - 请求参数。

json选项卡用于展示服务器对请求的响应示例。

/**
 * @ApiController(
 *     title="Пользователь",
 *     description="Описаие методов для работы с пользователем"
 * )
 * @ApiContent(
 *     title="Авторизация",
 *     description="Описание процесса авторизации"
 *  )
 * @ApiError(code="400", description="Bad Request – Your request sucks.")
 * @ApiError(code="401", description="Unauthorized – Your API key is wrong.")
 */
class User
{
    /**
      * @ApiAction(
      *     title="Список пользователей",
      *     description="Возвращает список пользователей",
      *     samples={
      *          @Sample(lang="javascript", code="alert('123');"),
      *          @Sample(lang="php", code="phpinfo();")
      *     }
      *     request=@Request(
      *          method="GET",
      *          url="/users",
      *          body="",
      *          params={
      *              @Param(title="param1", type="type1", defaultValue="val", description="descr"),
      *              @Param(title="param1", type="type1", defaultValue="val", description="descr")
      *          }
      *         response=@Response(body="json encoded array")
      *     )
      * )
      */
     public function listAction() {}
}