注解文檔

EasySwoole 允許對使用了注解控制器的注解的控制器類及 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 框架默認的控制器目錄下的使用控制器注解的所有控制器類并輸出對應文檔，用戶可以自己去做文檔權限控制，或者是對應的目錄限制。

生成離線文檔

注冊生成離線文檔命令

php easyswoole.php doc

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

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

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

DocCommand 類實現如下：

<?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';
    }
}

在項目根目錄下執行如下命令：

php easyswoole.php doc

即可生成對應的離線文檔。

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

注解使用示例

<?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("驗證碼"),
                type: ParamType::OBJECT,
                subObject: [
                    new Param(name: "code", from: ParamFrom::JSON, validate: [
                        new Required(),
                        new MaxLength(maxLen: 15),
                    ], description: "防偽編號"),
                    new Param(name: "phone", from: ParamFrom::JSON, description: "手機號")
                ])
        ],
        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: "賬號"),
                    new Param(name: "password", value: "1111", description: "密碼"),
                    new Param(name: "verify", value: "1111", description: new Description('驗證碼')),
                ]
            ),
            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: "結果", subObject: [
                        new Param(name: "id", value: 1, description: "用戶Id"),
                        new Param(name: "name", value: "八九", description: "昵稱")
                    ]),
                    new Param(name: "code", value: "200", description: "狀態碼"),
                ]
            ),
            new Example(
                [
                    new Param(name: "result", value: "fail", description: "結果"),
                    new Param(name: "code", value: "500", description: "狀態碼"),
                ]
            ),
            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("這是一個接口說明")
    )]
    public function login()
    {

    }
}