注解生成Api接口文档,自动注册路由、在线调试、Markdown文档

待更新 版本
待更新 版本更新时间
待更新 安装
155 star

v5版本 已内置兼容Webman

简介

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

特性

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

安装

1、安装扩展

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

composer require hg/apidoc

2、添加前端页面

点击此处,前往前端文件下载页面

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

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

3、配置异常响应

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

参考Webman官方文档找到你项目的异常处理类,或创建异常处理类

// 找到你的项目所配置的异常处理类,本示例为
// support/ExceptionHandle.php
public function render(Request $request, Throwable $exception): Response
{
    // Apidoc异常处理响应
    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);
}

使用

内容较多,请到官网了解 配置使用,配合webman的演示demo轻松上手.

效果图