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

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

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

简介

🤷‍♀️ Apidoc是什么?

Apidoc 是一个通过解析注解生成Api接口文档的PHP composer扩展,兼容LaravelThinkPHPHyperfWebman等框架。
全面的注解引用、数据表字段引用,简单的注解即可生成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. 添加前端页面

下载完成后解压,将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',
            ]
        ],
       ...   
    ]
];

配置说明

  1. apps设置文档的应用/版本。这里定义两个分别为CMS接口文档演示文档
  2. path 控制器目录地址。需要指定控制器目录地址
  3. key 唯一的key。这里的key就是模块名称

更多了解官方配置参数:https://docs.apidoc.icu/config/

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 用户信息

调试模式

截图

🚀 总结

好多人总觉得PHP语言开发大型项目并不是很适合,但现在PHP8出来后,个人觉得PHP8越来越适合开发大型项目,祝越来PHP越好,能够再众多的开发语言中再次脱颖而出。🚀🚀🚀 PHP是世界上最好的语言~ 🚀🚀🚀

🚀 要用注解,强烈推荐使用PHP8以上版本。以上是基于原始注解编写,你可以尝试使用 PHP8原生注解编写

更多了解,请到Apidoc官方文档 https://hg-code.gitee.io/apidoc-php

效果图(可选)

截图

截图