Apidoc 通過注解自動(dòng)生成API接口文檔

待更新 版本

待更新 版本更新時(shí)間

待更新 安裝

205 star

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

聲明：本插件為 Apidoc 官方插件，但是在webman基礎(chǔ)插件這里乜有，我只是提交上來，方便大家使用。順便補(bǔ)充了一下使用教程！

簡介

???♀? Apidoc是什么？

Apidoc 是一個(gè)通過解析注解生成Api接口文檔的PHP composer擴(kuò)展，兼容Laravel、ThinkPHP、Hyperf、Webman等框架。
全面的注解引用、數(shù)據(jù)表字段引用，簡單的注解即可生成Api文檔，而Apidoc不僅于接口文檔，在線接口調(diào)試、Mock調(diào)試數(shù)據(jù)、調(diào)試事件處理、Json/TypeScript生成、接口生成器、代碼生成器等諸多實(shí)用功能，致力于提高Api接口開發(fā)效率。

? 特性

開箱即用：無繁雜的配置、安裝后按文檔編寫注釋即可自動(dòng)生成API文檔。
輕松編寫：支持通用注釋引用、業(yè)務(wù)邏輯層、數(shù)據(jù)表字段的引用，幾句注釋即可完成。
在線調(diào)試：在線文檔可直接調(diào)試，并支持全局請求/Mock參數(shù)/事件處理，接口調(diào)試省時(shí)省力。
安全高效：支持訪問密碼驗(yàn)證、應(yīng)用/版本獨(dú)立密碼；支持文檔緩存。
多應(yīng)用/多版本：可適應(yīng)各種單應(yīng)用、多應(yīng)用、多版本的項(xiàng)目的Api管理。
分組/Tag：可對控制器/接口進(jìn)行多級分組或定義Tag。
Markdown文檔：支持.md文件的文檔展示。
Json/TypeScript生成：文檔自動(dòng)生成接口的Json及TypeScript。
代碼生成器：配置+模板即可快速生成代碼及數(shù)據(jù)表的創(chuàng)建，大大提高工作效率。

注解

什么是注解？

注解功能提供了代碼中的聲明部分都可以添加結(jié)構(gòu)化、機(jī)器可讀的元數(shù)據(jù)的能力，注解的目標(biāo)可以是類、方法、函數(shù)、參數(shù)、屬性、類常量。通過反射 API 可在運(yùn)行時(shí)獲取注解所定義的元數(shù)據(jù)。因此注解可以成為直接嵌入代碼的配置式語言。

通過注解的使用，在應(yīng)用中實(shí)現(xiàn)功能、使用功能可以相互解耦。某種程度上講，它可以和接口（interface）與其實(shí)現(xiàn)（implementation）相比較。但接口與實(shí)現(xiàn)是代碼相關(guān)的，注解則與聲明額外信息和配置相關(guān)。接口可以通過類來實(shí)現(xiàn)，而注解也可以聲明到方法、函數(shù)、參數(shù)、屬性、類常量中。因此它們比接口更靈活。

PHP8 注解

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

注解語法包含以下幾部分。首先，注解聲明總是以 #[ 開頭，以 ] 結(jié)尾來包圍。內(nèi)部則是一個(gè)或以逗號包含的多個(gè)注解。注解的名稱按使用命名空間：基礎(chǔ) 章節(jié)中描述，可以是非限定、限定、完全限定的名稱。注解的參數(shù)是可以選的，以常見的括號()包圍。注解的參數(shù)只能是字面值或者常量表達(dá)式。它同時(shí)接受位置參數(shù)和命名參數(shù)兩種語法。

通過反射 API 請求注解實(shí)例時(shí)，注解的名稱會被解析到一個(gè)類，注解的參數(shù)則傳入該類的構(gòu)造器中。因此每個(gè)注解都需要引入一個(gè)類。

1. 類注解

類注解定義是在 class 關(guān)鍵詞上方的注釋塊內(nèi)，比如常用的 Controller 和 AutoController 就是類注解的使用典范。

<?php
#[ClassAnnotation]
class Foo {}

2. 類方法注解

類方法注解定義是在方法上方的注釋塊內(nèi)，下面的代碼示例則為一個(gè)正確使用類方法注解的示例。

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

3. 類屬性注解

類屬性注解定義是在屬性上方的注釋塊內(nèi)，面的代碼示例則為一個(gè)正確使用類屬性注解的示例。

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

安裝

composer require hg/apidoc

注：在安裝本插件時(shí)，確保你已成功安裝webman的項(xiàng)目并成功運(yùn)行。

使用

1. 安裝插件

composer require hg/apidoc

注：在安裝本插件時(shí)，確保你已成功安裝webman的項(xiàng)目并成功運(yùn)行。

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項(xiàng)目public目錄下。目錄結(jié)構(gòu)如下所示：

.
├── 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。出現(xiàn)接口文檔頁面，表示安裝成功。

3. 配置參數(shù)

安裝插件后會在webman項(xiàng)目插件配置生成一個(gè)config/plugin/hg/apidoc/app.php的配置文件，以下為該文件可配置的參數(shù)說明。

<?php
return [
    'enable' => true,
    'apidoc' => [
        // （選配）文檔標(biāo)題，顯示在左上角與首頁
        'title' => '開源技術(shù)小棧',
        // （選配）文檔描述，顯示在首頁
        'desc' => '開源技術(shù)小棧CMS接口文檔',
        // （必須）設(shè)置文檔的應(yīng)用/版本
        'apps' => [
            [
                // （必須）標(biāo)題
                'title' => 'CMS接口文檔',
                // （必須）控制器目錄地址
                'path' => 'app\admin\controller',
                // （必須）唯一的key
                'key' => 'admin',
            ],
            [
                // （必須）標(biāo)題
                'title' => '演示文檔',
                // （必須）控制器目錄地址
                'path' => 'app\controller',
                // （必須）唯一的key
                'key' => 'api',
            ]
        ],
       ...   
    ]
];

配置說明

apps設(shè)置文檔的應(yīng)用/版本。這里定義兩個(gè)分別為CMS接口文檔和演示文檔

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

key 唯一的key。這里的key就是模塊名稱

4.0 編寫接口代碼

在app應(yīng)用目錄新建一個(gè)admin模塊，編寫一個(gè)登錄接口和獲取用戶信息接口

目錄結(jié)構(gòu)

.
├── 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 發(fā)行令牌")
     * @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' => '開源技術(shù)小棧', 'age' => 24]]);
    }
}

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

書寫注解規(guī)范

控制器必須use引入注釋解釋文件。即use hg\apidoc\annotation as Apidoc; 這句

PHP8原生注解，每個(gè)注解以 #[注解名("參數(shù)值",子參數(shù)名="子參數(shù)值",...)]

原始注解。每個(gè)注解以 @+注解名("參數(shù)名/值",子參數(shù)名="子參數(shù)值",...)