Apidoc 通过注解自动生成API接口文档

待更新 版本

待更新 版本更新时间

待更新 安装

218 star

https://github.com/HGthecode/apidoc-php

声明：本插件为 Apidoc 官方插件，但是在webman基础插件这里乜有，我只是提交上来，方便大家使用。顺便补充了一下使用教程！

简介

🤷‍♀️ Apidoc是什么？

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

✨ 特性

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

注解

什么是注解？

注解功能提供了代码中的声明部分都可以添加结构化、机器可读的元数据的能力，注解的目标可以是类、方法、函数、参数、属性、类常量。通过反射 API 可在运行时获取注解所定义的元数据。因此注解可以成为直接嵌入代码的配置式语言。

通过注解的使用，在应用中实现功能、使用功能可以相互解耦。某种程度上讲，它可以和接口（interface）与其实现（implementation）相比较。但接口与实现是代码相关的，注解则与声明额外信息和配置相关。接口可以通过类来实现，而注解也可以声明到方法、函数、参数、属性、类常量中。因此它们比接口更灵活。

PHP8 注解

PHP8 新增了注解特性：https://www.php.net/manual/zh/language.attributes.php

注解语法包含以下几部分。首先，注解声明总是以 #[ 开头，以 ] 结尾来包围。内部则是一个或以逗号包含的多个注解。注解的名称按使用命名空间：基础章节中描述，可以是非限定、限定、完全限定的名称。注解的参数是可以选的，以常见的括号()包围。注解的参数只能是字面值或者常量表达式。它同时接受位置参数和命名参数两种语法。

通过反射 API 请求注解实例时，注解的名称会被解析到一个类，注解的参数则传入该类的构造器中。因此每个注解都需要引入一个类。

1. 类注解

类注解定义是在 class 关键词上方的注释块内，比如常用的 Controller 和 AutoController 就是类注解的使用典范。

<?php #[ClassAnnotation] class Foo {}

2. 类方法注解

类方法注解定义是在方法上方的注释块内，下面的代码示例则为一个正确使用类方法注解的示例。

<?php class Foo { #[MethodAnnotation] public function bar() { // some code } }

3. 类属性注解

类属性注解定义是在属性上方的注释块内，面的代码示例则为一个正确使用类属性注解的示例。

<?php class Foo { #[PropertyAnnotation] private $bar; }

安装

composer require hg/apidoc

注：在安装本插件时，确保你已成功安装webman的项目并成功运行。

使用

1. 安装插件

composer require hg/apidoc

注：在安装本插件时，确保你已成功安装webman的项目并成功运行。

2. 添加前端页面

Gitee下载地址：https://gitee.com/hg-code/apidoc-php/releases/download/v5.2.1/apidoc-ui.zip
Github 下载地址：https://github.com/HGthecode/apidoc-php/releases/download/v5.2.1/apidoc-ui.zip

下载完成后解压，将apidoc文件夹拷贝到你的webman项目public目录下。目录结构如下所示：

. ├── app ├── public │   ├── 404.html │   ├── apidoc │   │   ├── assets │   │   ├── config.js │   │   ├── favicon.ico │   │   ├── index.html │   │   ├── monacoeditorwork │   │   ├── style.css │   │   └── utils │   └── favicon.ico

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

3. 配置参数

安装插件后会在webman项目插件配置生成一个config/plugin/hg/apidoc/app.php的配置文件，以下为该文件可配置的参数说明。

<?php return [ 'enable' => true, 'apidoc' => [ // （选配）文档标题，显示在左上角与首页 'title' => '开源技术小栈', // （选配）文档描述，显示在首页 'desc' => '开源技术小栈CMS接口文档', // （必须）设置文档的应用/版本 'apps' => [ [ // （必须）标题 'title' => 'CMS接口文档', // （必须）控制器目录地址 'path' => 'app\admin\controller', // （必须）唯一的key 'key' => 'admin', ], [ // （必须）标题 'title' => '演示文档', // （必须）控制器目录地址 'path' => 'app\controller', // （必须）唯一的key 'key' => 'api', ] ], ... ] ];

配置说明

apps设置文档的应用/版本。这里定义两个分别为CMS接口文档和演示文档

path 控制器目录地址。需要指定控制器目录地址

key 唯一的key。这里的key就是模块名称

4.0 编写接口代码

在app应用目录新建一个admin模块，编写一个登录接口和获取用户信息接口

目录结构

. ├── app │   ├── admin │   │   └── controller │   │   └── LoginController.php

控制器LoginController.php 文件

<?php /** * @desc LoginController * @author Tinywan(ShaoBo Wan) * @email 756684177@qq.com * @date 2024/1/13 19:46 */ declare(strict_types=1); namespace app\admin\controller; use support\Request; use hg\apidoc\annotation as Apidoc; use support\Response; /** * @Apidoc\Title("登录管理") */ class LoginController { /** * @Apidoc\Title("1.0 发行令牌") * @Apidoc\Url("admin/login/token") * @Apidoc\Method("POST") * @Apidoc\Query("username", type="string",require=true, desc="账号",default="Tinywan") * @Apidoc\Query("password", type="string",require=true, desc="密码",default="123456") * @Apidoc\Returned("access_token", type="string", desc="访问令牌") */ public function token(Request $request): Response { var_dump($request->all()); return json(['code' => 0, 'msg' => 'success', 'data' => ['access_token' => time()]]); } /** * @Apidoc\Title("2.0 用户信息") * @Apidoc\Url("admin/login/user") * @Apidoc\Method("GET") * @Apidoc\Query("id", type="int", require=true, desc="用户id",default=0) */ public function user(Request $request): Response { return json(['code' => 0, 'msg' => 'success', 'data' => ['username' => '开源技术小栈', 'age' => 24]]); } }

以上案例是原始注解。不是PHP8原生注解。

书写注解规范

控制器必须use引入注释解释文件。即use hg\apidoc\annotation as Apidoc; 这句

PHP8原生注解，每个注解以 #[注解名("参数值",子参数名="子参数值",...)]

原始注解。每个注解以 @+注解名("参数名/值",子参数名="子参数值",...)