ThinkPHP5 Api Doc 项目教程

1. 项目的目录结构及介绍

api-doc/
├── src/
│   ├── config/
│   │   └── doc.php
│   ├── controller/
│   │   └── Demo.php
│   └── ...
├── LICENSE
├── README.md
├── composer.json
└── demo.php

目录结构说明

• src/: 项目的主要源代码目录。
  • config/: 配置文件目录，包含 doc.php 配置文件。
  • controller/: 控制器目录，包含示例控制器 Demo.php。
• LICENSE: 项目的开源许可证文件。
• README.md: 项目的说明文档。
• composer.json: Composer 依赖管理文件。
• demo.php: 示例文件，用于演示如何使用该扩展。

2. 项目的启动文件介绍

项目的启动文件主要是 demo.php，它是一个示例文件，展示了如何在控制器中使用注释来生成 API 文档。

示例代码

<?php
namespace app\index\controller;

use think\Controller;

/**
 * @title 测试demo
 * @description 接口说明
 * @group 接口分组
 * @header name:key require:1 default: desc:秘钥(区别设置)
 * @param name:public type:int require:1 default:1 other: desc:公共参数(区别设置)
 */
class Demo extends Controller {
    /**
     * @title 测试demo接口
     * @description 接口说明
     * @author 开发者
     * @url /index/demo
     * @method GET
     *
     * @header name:device require:1 default: desc:设备号
     *
     * @param name:id type:int require:1 default:1 other: desc:唯一ID
     *
     * @return name:名称
     * @return mobile:手机号
     * @return list_messages:消息列表@
     * @list_messages message_id:消息ID content:消息内容
     * @return object:对象信息@
     * @object attribute1:对象属性1 attribute2:对象属性2
     * @return array:数组值#
     * @return list_user:用户列表@
     * @list_user name:名称 mobile:手机号 list_follow:关注列表@
     * @list_follow user_id:用户id name:名称
     */
    public function index() {
        //接口代码
        $device = $this->request->header('device');
        echo json_encode(["code"=>200, "message"=>"success", "data"=>['device'=>$device]]);
    }

    /**
     * @title 登录接口
     * @description 接口说明
     * @author 开发者
     * @url /api/demo
     * @method GET
     * @module 用户模块
     * @param name:name type:int require:1 default:1 other: desc:用户名
     * @param name:pass type:int require:1 default:1 other: desc:密码
     *
     * @return name:名称
     * @return mobile:手机号
     */
    public function login(Request $request) {
        //接口代码
        $device = $request->header('device');
        echo json_encode(["code"=>200, "message"=>"success", "data"=>['device'=>$device]]);
    }
}

3. 项目的配置文件介绍

项目的配置文件主要位于 src/config/doc.php。该文件包含了生成 API 文档所需的配置参数。

配置文件示例

<?php

return [
    // 控制器命名空间
    'controller' => [
        'app\\api\\controller\\Demo' // 控制器的命名空间+控制器名称
    ],
    // 其他配置参数
    // ...
];

配置参数说明

• controller: 指定控制器的命名空间和控制器名称，用于生成 API 文档。
• 其他配置参数: 根据项目需求，可以添加其他配置参数，如全局参数设置、类参数设置等。

通过以上配置，可以生成详细的 API 文档，并在浏览器中访问 http://你的域名/doc 或 http://你的域名/index.php/doc 查看生成的文档。