YiluPHP 2.0文档

文档自动生成

浏览数 100913
YiluPHP具有根据controller中的注释自动生成文档的功能。只要在controller中根据规定的格式编写注释就能自动生成接口文档，文档的访问地址是：http://你的域名/api_docs。自动生成的文档具有以下特性：
  • 可以根据系统版本号筛选接口；
  • 可以通过关键字搜索接口；
  • 提供可以接口调试功能；
  • 默认只能在dev和local环境中才能访问；
  • 可以设置访问密码，任何环境中都能通过密码访问；
接口文档可以在配置文件中设置密码（$config['visit_api_docs_password']），如果没有设置密码，则只能在dev和local环境查看文档，如果设置了密码，不管在哪个环境中都需要密码才能访问。
我们先看一下框架自带的welcome页面的注释，以下是在其controller中的注释
<?php
/**
 * @group 这是分组名称
 * @version
 * @name 欢迎页，Controller的示例
 * @desc 请在Controller中保持此格式的注释，后期会提供根据此注释自动生成接口文档的功能
 * @method GET/POST
 * @uri /welcome
 * @param integer article_id 文章ID 可选 示例用
 * @param string title 标题 可选 示例用
 * @param string mobile 手机号 可选 示例用，需要使用RSA加密
 * @return html
 * @exception
 *  1 参数错误[article_id]
 *  2 标题太长了
 *  100 参数错误[mobile]
 */
PHP

以文档中的展示效果见下图


注释是/**开头，以*/结尾，注释中需要包含以下选项，每一个选项名称后面都需要用空格分隔：
@group 是文档的分组，分组后的表现是会在页面左侧菜单中分组显示，这个是可选项，如果不设置分组则以一级菜单显示。
@version 指版本号，即使用到本接口的系统版本，多个版本中使用空格分隔，这个也是可选项
@name 是接口名称，必须设置，如果不设置就不会在文档中展现
@desc 是接口的描述信息，为可选项
@method 是接口请求方法，如GET、POST，为必选项
@uri 接口访问地址，为必选项
@param 请求参数，如果没有参数可以不设置，也可以设置多个参数，一行一个，每一个参数都由5个部分显示，各部分之间使用空格分隔。第一部分是参数类型，如string、integer；第二部分是参数的键名；第三部分是参数的显示名称；第四部分为标注此参数是否必选；第五部分是参数的其它描述信息。
@return 返回数据的描述，必选项，文档中会根据注释中的排版显示。
@exception 异常信息枚举，如各错误码及其意义，可选项，文档中会根据注释中的排版显示。

评论（0）
还没有人评论哦
我来说说