注解自动生成Api接口文档

v4.1.4 版本
2022-11-29 版本更新时间
15163 安装
39 star

简介

Apidoc是一个通过解析注解生成Api接口文档的PHP composer扩展;兼容Laravel、ThinkPHP、Hyperf、Webman等框架。
全面的注解引用、数据表字段引用,简单的注解即可生成Api文档,而Apidoc不仅于接口文档,在线接口调试、Mock调试数据、调试事件处理、Json/TypeScript生成、批量测试、接口分享、代码生成器、Api市场等诸多实用功能,致力于提高Api接口开发效率。

特性

  • 开箱即用:无繁杂的配置、安装后按文档编写注释即可自动生成API文档。
  • 轻松编写:支持通用注释引用、业务逻辑层、数据表字段的引用,几句注释即可完成。
  • 在线调试:在线文档可直接调试,并支持全局请求/Mock参数/事件处理,接口调试省时省力。
  • 安全高效:支持访问密码验证、应用/版本独立密码;支持文档缓存。
  • 多应用/多版本:可适应各种单应用、多应用、多版本的项目的Api管理。
  • 分组/Tag:可对控制器/接口进行多级分组或定义Tag。
  • Markdown文档:支持.md文件的文档展示。
  • Json/TypeScript生成:文档自动生成接口的Json及TypeScript。
  • 代码生成器:配置+模板即可快速生成代码及数据表的创建,大大提高工作效率。

安装

需手动配置兼容,可参考详细的安装文档 https://docs.apidoc.icu/guide/install/other.html

1、安装扩展

进入项目根目录,执行如下命令:

composer require hg/apidoc

2、创建配置文件

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
        ],
        //... 更多配置项请查看文档
    ]
];

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、创建中间件

由于Apidoc兼容多种框架,需根据框架情况,手动实现以下中间件的方法

(1)创建ApidocService中间件

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\CommonService;
use hg\apidoc\utils\ConfigProvider;
use support\Db;

class ApidocServiceProvider implements MiddlewareInterface
{
    use CommonService;

    public function process(Request $request, callable $next): Response
    {
        $this->register();
        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)
    {
    }

    /**
     * 获取语言方法
     */
    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 ,出现接口文档页面,表示安装成功。

使用

内容较多,请到官网了解 配置使用

效果图(可选)