500错误

伪静态问题

由于使用命令行启动的项目没有伪静态规则，（如ThinkPHP使用php think run运行）， 所以Apidoc无法正常访问所需接口导致； 解决方案： 1、使用集成环境运行，并配置伪静态规则，参考404-页面提示错误 2、前端配置文件指定路径，参考404-配置前端请求host参数

开启密码访问后报错

当开启访问授权配置时，因框架的全局异常处理，没有将401状态码正常返回时出现

// （必须）权限认证配置
'auth'               => [
    // 是否启用密码验证
    'enable'     => true,
    //...
],

ThinkPHP框架在未对全局异常处理进行修改的，出现以下错误：

Laravel框架在未对全局异常处理进行修改的，出现如下错误：

可参考以下异常处理类来处理

// Tp6示例
// app/ExceptionHandle.php
public function render($request, Throwable $e): Response
{
    // 添加自定义异常处理机制
    if ($e instanceof \hg\apidoc\exception\HttpException) {
        return json(
            [
                "code" => $e->getCode(),
                "message" => $e->getMessage(),
            ],
            $e->getStatusCode()
        );
    }
}

// Laravel 示例
// app/Exceptions/Handler.php
public function register()
{
    $this->reportable(function (Throwable $e) {
        if ($e instanceof \hg\apidoc\exception\HttpException) {
            return abort(
                $e->getStatusCode(),
                $e->getMessage(),
            );
        }
    });
}

// Webman 示例
// support/ExceptionHandle.php
public function render(Request $request, Throwable $exception): Response
{
    if ($exception instanceof \hg\apidoc\exception\HttpException) {
        return response(json_encode([
            "code" => $exception->getCode(),
            "message" => $exception->getMessage(),
        ],JSON_UNESCAPED_UNICODE), $exception->getStatusCode());
    }
    
    return parent::render($request, $exception);
}

注解错误

访问apidoc页面时，如出现如下错误信息；通常有具体的描述，根据描述信息排查即可

缺少注解解释文件

项目所有被解析文件的注释中存在 @XXX 的，都需use引入注释解释文件，如出现以下错误

可根据提示在相应的文件里，加上use解释文件

<?php
namespace app\controller;

// 加上这句，解决Apidoc注解报错
use hg\apidoc\annotation as Apidoc;
// 通过use自定义解释文件，解决下面@abc的错误
// use app\utils\Abc;

/**
 * @Apidoc\Title("基础示例")
 */
class BaseDemo
{
    /**
     * @Apidoc\Title("引入通用注释")
     * @abc 错误示例，这样不存在解释文件的注释会报错；可增加use解释文件，或去除@、或通过配置忽略（推荐）
     */
    public function test(){
        //...
    }
}

自定义解释文件

// app/utils/Abc.php 解释文件内容
<?php
namespace app\utils;
use Doctrine\Common\Annotations\Annotation;

/**
 * 自定义参数解释文件
 * @package hg\apidoc\annotation
 * @Annotation
 * @Target({"METHOD","CLASS"})
 */
class Abc extends Annotation
{}

配置忽略带@的注解报错：

// apidoc.php
[
    'ignored_annitation'=>['abc','name']
]

未知异常

如页面显示无具体错误信息，先根据对应框架的安装教程页，配置配置异常响应，可尝试开启框架的DEBUG模式，再次访问通常就会出现详细的错误信息了。