注解文檔

EasySwoole 允許對(duì)使用了注解控制器的注解的控制器類及 action，生成 api 接口文檔。

控制器輸出文檔

<?php
namespace App\HttpController;

use EasySwoole\HttpAnnotation\AnnotationController;
use EasySwoole\HttpAnnotation\Document\Document;

class Index extends AnnotationController
{
    public function doc()
    {
        $path      = __DIR__;
        $namespace = 'App\HttpController';
        $doc       = new Document($path, $namespace);
        $this->response()->withAddedHeader('Content-Type', "text/html;charset=utf-8");
        $this->response()->write($doc->scanToHtml());
    }
}

例如在以上的代碼中，我們就是直接掃描 EasySwoole 框架默認(rèn)的控制器目錄下的使用控制器注解的所有控制器類并輸出對(duì)應(yīng)文檔，用戶可以自己去做文檔權(quán)限控制，或者是對(duì)應(yīng)的目錄限制。

生成離線文檔

注冊(cè)生成離線文檔命令

php easyswoole.php doc

在使用命令之前需要先在 EasySwoole 框架中注冊(cè)生成離線文檔命令，修改 EasySwoole 框架根目錄的 bootstrap.php 文件，如下：

<?php
// bootstrap.php
// 全局bootstrap事件
date_default_timezone_set('Asia/Shanghai');

\EasySwoole\Command\CommandManager::getInstance()->addCommand(new \App\Command\DocCommand());

DocCommand 類實(shí)現(xiàn)如下：

<?php

namespace App\Command;

use EasySwoole\Command\AbstractInterface\CommandHelpInterface;
use EasySwoole\Command\CommandManager;
use EasySwoole\EasySwoole\Command\CommandInterface;
use EasySwoole\HttpAnnotation\Document\Document;

class DocCommand implements CommandInterface
{
    public function commandName(): string
    {
        return 'doc';
    }

    public function exec(): ?string
    {
        $dir = CommandManager::getInstance()->getOpt("dir", EASYSWOOLE_ROOT . '/App/HttpController');
        if (empty($dir)) {
            return "php easyswoole.php doc --dir=DIR";
        }

        $fix      = "doc_" . date("Ymd");
        $maxCount = 1;
        if ($dh = opendir(getcwd())) {
            while (($file = readdir($dh)) !== false) {
                if (is_file($file)) {
                    if (str_starts_with($file, $fix)) {
                        $name  = explode(".", $file)[0];
                        $count = (int)substr($name, strlen($fix) + 1);
                        if ($count >= $maxCount) {
                            $maxCount = $count + 1;
                        }
                    }
                }
            }
            closedir($dh);
        }

        $finalFile = getcwd();

        $namespace = 'App\HttpController';
        $doc       = new Document($dir, $namespace);
        $html      = $doc->scanToHtml();
        $finalFile = $finalFile . "/{$fix}_{$maxCount}.html";
        file_put_contents($finalFile, $html);

        return "create doc file :{$finalFile}";
    }

    public function help(CommandHelpInterface $commandHelp): CommandHelpInterface
    {
        $commandHelp->addActionOpt('--dir', 'scanned directory or file');
        return $commandHelp;
    }

    public function desc(): string
    {
        return 'build api doc by annotations';
    }
}

在項(xiàng)目根目錄下執(zhí)行如下命令：

php easyswoole.php doc

即可生成對(duì)應(yīng)的離線文檔。

注意，僅當(dāng)有使用了 Api 注解的控制器方法才會(huì)被渲染到離線文檔中。

注解使用示例

<?php

namespace App\HttpController\Api;

use EasySwoole\HttpAnnotation\Attributes\Api;
use EasySwoole\HttpAnnotation\Attributes\ApiGroup;
use EasySwoole\HttpAnnotation\Attributes\Description;
use EasySwoole\HttpAnnotation\Attributes\Example;
use EasySwoole\HttpAnnotation\Attributes\Param;
use EasySwoole\HttpAnnotation\Enum\HttpMethod;
use EasySwoole\HttpAnnotation\Enum\ParamFrom;
use EasySwoole\HttpAnnotation\Enum\ParamType;
use EasySwoole\HttpAnnotation\Validator\MaxLength;
use EasySwoole\HttpAnnotation\Validator\Required;

#[ApiGroup(
    groupName: "Api.Auth", description: new Description(__DIR__ . '/../../../res/description.md', Description::MARKDOWN_FILE)
)]
class Auth extends ApiBase
{
    #[Api(
        apiName: "login",
        allowMethod: HttpMethod::GET,
        requestPath: "/auth/login.html",
        requestParam: [
            new Param(name: "account", from: ParamFrom::GET, validate: [
                new Required(),
                new MaxLength(maxLen: 15),
            ], description: new Description("用戶登錄的賬戶Id")),
            new Param(name: "password", from: ParamFrom::GET, validate: [
                new Required(),
                new MaxLength(maxLen: 15),
            ], description: new Description("密碼")),
            new Param(name: "verify", from: ParamFrom::JSON,
                description: new Description("驗(yàn)證碼"),
                type: ParamType::OBJECT,
                subObject: [
                    new Param(name: "code", from: ParamFrom::JSON, validate: [
                        new Required(),
                        new MaxLength(maxLen: 15),
                    ], description: "防偽編號(hào)"),
                    new Param(name: "phone", from: ParamFrom::JSON, description: "手機(jī)號(hào)")
                ])
        ],
        responseParam: [
            new Param(
                name: "code", type: ParamType::STRING
            ),
            new Param(
                name: "Result",
                type: ParamType::LIST,
                subObject: [
                    new Param("token"),
                    new Param("expire")
                ]
            ),
            new Param("msg")
        ],
        requestExamples: [
            new Example(
                [
                    new Param(name: "account", value: "1111", description: "賬號(hào)"),
                    new Param(name: "password", value: "1111", description: "密碼"),
                    new Param(name: "verify", value: "1111", description: new Description('驗(yàn)證碼')),
                ]
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/json.json', Description::JSON_FILE)
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/xml.xml', Description::XML_FILE)
            ),
        ],
        responseExamples: [
            new Example(
                [
                    new Param(name: "result", description: "結(jié)果", subObject: [
                        new Param(name: "id", value: 1, description: "用戶Id"),
                        new Param(name: "name", value: "八九", description: "昵稱")
                    ]),
                    new Param(name: "code", value: "200", description: "狀態(tài)碼"),
                ]
            ),
            new Example(
                [
                    new Param(name: "result", value: "fail", description: "結(jié)果"),
                    new Param(name: "code", value: "500", description: "狀態(tài)碼"),
                ]
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/json.json', Description::JSON_FILE)
            ),
            new Example(
                new Description(__DIR__ . '/../../../res/xml.xml', Description::XML_FILE)
            ),
        ],
        description: new Description("這是一個(gè)接口說(shuō)明")
    )]
    public function login()
    {

    }
}