🤷♀️ Apidoc是什么?
Apidoc 是一个通过解析注解生成Api接口文档的PHP composer扩展,兼容Laravel
、ThinkPHP
、Hyperf
、Webman
等框架。全面的注解引用、数据表字段引用,简单的注解即可生成Api文档,而Apidoc不仅于接口文档,在线接口调试、Mock调试数据、调试事件处理、Json/TypeScript生成、接口生成器、代码生成器等诸多实用功能,致力于提高Api接口开发效率。
注解功能提供了代码中的声明部分都可以添加结构化、机器可读的元数据的能力, 注解的目标可以是类、方法、函数、参数、属性、类常量。通过 反射 API 可在运行时获取注解所定义的元数据。因此注解可以成为直接嵌入代码的配置式语言。
通过注解的使用,在应用中实现功能、使用功能可以相互解耦。某种程度上讲,它可以和接口(interface)与其实现(implementation)相比较。但接口与实现是代码相关的,注解则与声明额外信息和配置相关。接口可以通过类来实现,而注解也可以声明到方法、函数、参数、属性、类常量中。因此它们比接口更灵活。
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的项目并成功运行。
下载完成后解压,将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。出现接口文档页面,表示安装成功。
安装插件后会在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就是模块名称更多了解官方配置参数:https://docs.apidoc.icu/config/
在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
原生注解,每个注解以 #[注解名("参数值",子参数名="子参数值",...)]
@+注解名("参数名/值",子参数名="子参数值",...)
代码编写好后,我们就可以查看注解生成的接口文档了,打开浏览器访问 http://127.0.0.1:8787/apidoc/index.html,可以看到刚才定义的两个接口都已经在接口文档里了。
admin/login/token
admin/login/user
查看JSON格式
调试模式
调试模式