500错误

HG大约 2 分钟

500错误

伪静态问题

error-500-1

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

开启密码访问后报错

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

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

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

error-auth-1

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

error-500-1

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

// 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页面时,如出现如下错误信息;通常有具体的描述,根据描述信息排查即可

error-501

缺少注解解释文件

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

error-500

可根据提示在相应的文件里,加上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']
]

未知异常

error-500-1

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