thinkphp5的API文档生成库api_doc使用总结

author: hjb2722404 head: https://avatars1.githubusercontent.com/u/10215241?v=3&s=460 date: 2017-03-15 title: thinkphp5的API文档生成库api_doc使用总结 tags: : API 自动化 category: 技术-后端 status: public summary: 本文记录了使用TP5的文档自动生成库api_doc的一点心得体会。

api_doc简介

​ api_doc是github上开源的一个TP5的API文档自动生成库，基于PHP语言编写，相比于其他API文档生成工具或库，它有以下优点：

  • 不依赖其他库和环境
  • 安装配置简单快捷
  • 生成的文档界面直观，层级清晰

安装

### 通过命令行工具下载
$ git clone https://github.com/NTASTE/php_api_doc.git

通过github项目主页下载

打开该项目的github主页

点击ZIP下载按钮，下载后解压。

将文件夹改名为api_doc并将整个文件夹移动到TP5项目的根目录，如图所示：

mark

配置

进入api_doc/config目录，编辑config.php文件：

mark

PS： 注意API控制器目录是相对于config.php的路径，如上例所对应的目录结构：

mark

使用

### API输出数据说明

api_doc对于API输出数据的说明采用了注释法，直接将注释写在API方法之前就行,一般都会有一个@desc和若干个@return字段，@return字段的格式为：@return 返回字段类型 返回字段名称 返回字段说明，返回字段类型有以下几种：


        'string'  => '字符串',
        'int'     => '整型',
        'float'   => '浮点型',
        'boolean' => '布尔型',
        'date'    => '日期',
        'array'   => '数组',
        'fixed'   => '固定值',
        'enum'    => '枚举类型',
        'object'  => '对象',

示例文件

/application/v1/controller/Order.php:

<?php

class Order {

    /**
     * 测试接口
     * @desc 用于获取多个用户基本信息
     * @return int code 操作码，0表示成功
     * @return array list 用户列表
     * @return int list[].id 用户ID
     * @return string list[].name 用户名字
     * @return string list[].note 用户来源
     * @return string msg 提示信息
     */

    public function test(){
        return [];
    }

    /**
     * 测试接口1
     * @desc 用于获取多个用户基本信息
     * @return int code 操作码，0表示成功
     * @return array list 用户列表
     * @return int list[].id 用户ID
     * @return string list[].name 用户名字
     * @return string list[].note 用户来源
     * @return string msg 提示信息
     */

    public function demo(){
        return [];
    }

    public function getRules(){

         return [
            'demo' => [
                'tel' => [
                    'name'    => 'tel',
                    'type'    => 'int',
                    'min'     => 11,
                    'require' => true,
                    'desc'    => '电话号码'
                ],
                'password' => [
                    'name'    => 'password',
                    'type'    => 'int',
                    'min'     => 6,
                    'require' => true,
                    'desc'    => '登录密码'
                ]
            ],

            'test' => [
                'userIds' => [
                    'name'    => 'user_ids',
                    'type'    => 'array',
                    'format'  => 'explode',
                    'require' => true,
                    'default' => '10',
                    'range'   => [10,100],
                    'desc'    => '用户ID，多个以逗号分割'
                ],
            ],
        ];
    }
}

API输入参数说明

对于API的输入参数说明，api_doc采用了统一在API类下面设置rules来实现，如以上文件末尾所示例的，该方法统一为getRules()方法，该方法返回一个多维数组，数组的第一维是API的方法名，第二维是输入参数标识，第三维是该参数的对该参数的属性要求，一般来说有以下几个：

                    'name'    => 'user_ids', // 参数名称，API从请求中取参数以此名称为准
                    'type'    => 'array',    //参数类型
                    'format'  => 'explode',  //参数格式
                    'require' => true,       //是否必须
                    'default' => '10',       //默认值
                    'range'   => [10,100],   //取值范围
                    'desc'    => '用户ID，多个以逗号分割' //对参数的说明和描述

效果

mark

mark

mark