Webman/其它框架安装

其它框架兼容

理论上 Apidoc 可通过手动配置来兼容任何基于 composer 的框架，此处以 Webman 框架为例来手动适配兼容

1、安装插件

进入项目根目录，执行如下命令：

composer require hg/apidoc

2、创建配置文件

根据框架规范在指定目录创建配置文件，以 webman 为例。

在 config/plugin目录下创建 hg/apidoc/目录，并在该目录下创建app.php route.php文件，创建后目录结构如下：

|- config
   |- plugin
     |-hg
       |-apidoc
         |- app.php
         |- route.php

app.php 代码

<?php
return [
    'enable'  => true,
    'apidoc' => [
        // （选配）文档标题，显示在左上角与首页
        'title'              => 'Apidoc',
        // （选配）文档描述，显示在首页
        'desc'               => '',
        // （必须）设置文档的应用/版本
        'apps'           => [
            [
                // （必须）标题
                'title'=>'Api接口',
                // （必须）控制器目录地址
                'path'=>'app\controller',
                // （必须）唯一的key
                'key'=>'api',
            ]
        ],
        // （必须）指定通用注释定义的文件地址
        'definitions'        => "app\common\controller\Definitions",
        // （必须）自动生成url规则，当接口不添加@Apidoc\Url ("xxx")注解时，使用以下规则自动生成
        'auto_url' => [
            // 字母规则，lcfirst=首字母小写；ucfirst=首字母大写；
            'letter_rule' => "lcfirst",
            // url前缀
            'prefix'=>"",
        ],
        // （必须）缓存配置
        'cache'              => [
            // 是否开启缓存
            'enable' => false,
        ],
        // （必须）权限认证配置
        'auth'               => [
            // 是否启用密码验证
            'enable'     => false,
            // 全局访问密码
            'password'   => "123456",
            // 密码加密盐
            'secret_key' => "apidoc#hg_code",
            // 授权访问后的有效期
            'expire' => 24*60*60
        ],
        // 全局参数
        'params'=>[
            // （选配）全局的请求Header
            'header'=>[
                // name=字段名，type=字段类型，require=是否必须，default=默认值，desc=字段描述
                ['name'=>'Authorization','type'=>'string','require'=>true,'desc'=>'身份令牌Token'],
            ],
            // （选配）全局的请求Query
            'query'=>[
                // 同上 header
            ],
            // （选配）全局的请求Body
            'body'=>[
                // 同上 header
            ],
        ],
        // 全局响应体
        'responses'=>[
            // 成功响应体
            'success'=>[
                ['name'=>'code','desc'=>'业务代码','type'=>'int','require'=>1],
                ['name'=>'message','desc'=>'业务信息','type'=>'string','require'=>1],
                //参数同上 headers；main=true来指定接口Returned参数挂载节点
                ['name'=>'data','desc'=>'业务数据','main'=>true,'type'=>'object','require'=>1],
            ],
            // 异常响应体
            'error'=>[
                ['name'=>'code','desc'=>'业务代码','type'=>'int','require'=>1,'md'=>'/docs/HttpError.md'],
                ['name'=>'message','desc'=>'业务信息','type'=>'string','require'=>1],
            ]
        ],
        //（选配）默认作者
        'default_author'=>'',
        //（选配）默认请求类型
        'default_method'=>'GET',
        //（选配）允许跨域访问
        'allowCrossDomain'=>false,
        /**
         * （选配）解析时忽略带@注解的关键词，当注解中存在带@字符并且非Apidoc注解，如 @key test，此时Apidoc页面报类似以下错误时:
         * [Semantical Error] The annotation "@key" in method xxx() was never imported. Did you maybe forget to add a "use" statement for this annotation?
         */
        'ignored_annitation'=>[],

        // （选配）数据库配置
        'database'=>[],
        // （选配）Markdown文档
        'docs'              => [],
        // （选配）接口生成器配置 注意：是一个二维数组
        'generator' =>[]
    ]
];

route.php 代码

<?php
use Webman\Route;
use hg\apidoc\providers\CommonService;
// 注册Apidoc所需路由
CommonService::registerApidocRoutes(function ($item){
    Route::any($item['uri'],[hg\apidoc\Controller::class,$item['route']]);
});

3、创建中间件

（1）创建 ApidocService 中间件

根据框架规范在指定目录创建中间件文件，以 Webman 为例在app/middleware/目录创建ApidocServiceProvider.php文件

ApidocServiceProvider.php 代码

<?php
namespace app\middleware;

use Webman\MiddlewareInterface;
use Webman\Http\Response;
use Webman\Http\Request;
use hg\apidoc\providers\BaseService;
use hg\apidoc\utils\ConfigProvider;
use support\Db;

class ApidocServiceProvider implements MiddlewareInterface
{
    use BaseService;

    public function process(Request $request, callable $next): Response
    {
        $this->initConfig();
        if ($request->method() == "GET"){
            $params = $request->get();
        }else{
            $params = $request->post();
        }
        $config =  ConfigProvider::get();
        $config['request_params'] = $params;
        ConfigProvider::set($config);
        $response = $next($request);
        return $response;
    }

    /**
     * 获取apidoc配置，根据框架返回配置文件的内容
     */
    static function getApidocConfig()
    {
        return config('plugin.hg.apidoc.app.apidoc');
    }

    /**
     * 注册Apidoc所需路由
     */
    static function registerRoute($route)
    {
        // 由于已在配置文件config/plugin/hg/apidoc/route.php中注册了Apidoc路由，此处无需再实现
    }

    /**
     * 数据库查询方法
     */
    static function databaseQuery($sql)
    {
        return Db::select($sql);
    }

    /**
     * 项目跟目录地址
     */
    static function getRootPath()
    {
        return BASE_PATH."/";
    }

    /**
     * 缓存目录地址
     */
    static function getRuntimePath()
    {
        return BASE_PATH."/runtime/";
    }

    /**
     * 语言包注册
     */
    static function setLang($locale)
    {
//        $this->langLocale = $locale;
    }

    /**
     * 获取语言方法
     */
    static function getLang($lang): string
    {
        return $lang;
    }

    /**
     * 处理请求响应返回的数据
     */
    static function handleResponseJson($res)
    {
        return json($res);
    }

    /**
     * 数据表前缀
     */
    static function getTablePrefix(){
        return "";
    }

}

（2）注册中间件

以 Webman 为例，config/middleware.php注册全局中间件

<?php
return [
    '' => [
        // 加上这句
        \app\middleware\ApidocServiceProvider::class
    ]
];

4、添加前端页面

下载完成后解压，将 apidoc 文件夹拷贝到你的项目 public 目录下

打开浏览器访问 http://你的域名/apidoc/index.html ，出现接口文档页面，表示安装成功。

配置异常响应

由于框架会对全局异常进行处理，如 apidoc 的异常未被正确响应，会导致页面打不开或报错，配置以下异常处理来解决问题。

// 找到你的项目所配置的异常处理类，本示例为
// 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);
}