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

待更新 版本

待更新 版本更新时间

待更新 安装

151 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原生注解，每个注解以 #[注解名("参数值",子参数名="子参数值",...)]

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

5.0 接口文档和调试

代码编写好后，我们就可以查看注解生成的接口文档了，打开浏览器访问 http://127.0.0.1:8787/apidoc/index.html，可以看到刚才定义的两个接口都已经在接口文档里了。

1.0 发行令牌admin/login/token
2.0 用户信息admin/login/user

1.0 发行令牌

查看JSON格式

调试模式

2.0 用户信息