投稿
  1. 极客之音首页
  2. 后端开发
  3. PHP

通过PHP注解Apidoc自动生成API接口文档在Webman框架

李, 若俞 • • PHP • 阅读 66

Apidoc

🤷‍♀️ 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;
}

使用

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。出现接口文档页面，表示安装成功。

通过PHP注解Apidoc自动生成API接口文档在Webman框架

3. 配置参数

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

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


use supportRequest;
use hgapidocannotation as Apidoc;
use supportResponse;

/**
 * @ApidocTitle("登录管理")
 */
class LoginController
{
    /**
     * @ApidocTitle("1.0 发行令牌")
     * @ApidocUrl("admin/login/token")
     * @ApidocMethod("POST")
     * @ApidocQuery("username", type="string",require=true, desc="账号",default="Tinywan")
     * @ApidocQuery("password", type="string",require=true, desc="密码",default="123456")
     * @ApidocReturned("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()]]);
    }

    /**
     * @ApidocTitle("2.0 用户信息")
     * @ApidocUrl("admin/login/user")
     * @ApidocMethod("GET")
     * @ApidocQuery("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 hgapidocannotation as Apidoc; 这句
  • PHP8原生注解，每个注解以 #[注解名("参数值",子参数名="子参数值",...)]
  • 原始注解。每个注解以 @+注解名("参数名/值",子参数名="子参数值",...)

5.0 接口文档和调试

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

通过PHP注解Apidoc自动生成API接口文档在Webman框架
  • 1.0 发行令牌admin/login/token
  • 2.0 用户信息admin/login/user

1.0 发行令牌

查看JSON格式

通过PHP注解Apidoc自动生成API接口文档在Webman框架

调试模式

通过PHP注解Apidoc自动生成API接口文档在Webman框架

2.0 用户信息

调试模式

通过PHP注解Apidoc自动生成API接口文档在Webman框架

🚀 总结

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

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

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


原文始发于微信公众号（开源技术小栈）：通过PHP注解Apidoc自动生成API接口文档在Webman框架

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。

文章由极客之音整理，本文链接：https://www.bmabk.com/index.php/post/247837.html

赞 (0)
李, 若俞的头像李, 若俞
0 0

相关推荐

发表回复

登录后才能评论
极客之音——专业性很强的中文编程技术网站，欢迎收藏到浏览器，订阅我们！