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