PHP接口API文档转换SDK【神器】

更新记录：

• 2015-11-12 增加javanative原生代码写法，免依赖包
• 2015-11-17 增加swift Http请求类输出，完美适配CI框架（详情）
• 2015-11-19 增加Ios数据类输出
• 2015-11-20 增加自定义文档保存路径，完美适配ThinkPHP框架（详情）
• 2015-11-25 增加文件夹下载，请求地址为document_sdk/FolderDownLoad.php?document=
• 2015-12-23 增加多个共享数据同层模型，且可使其数据为空，兼容java与swift错误。
• 2015-12-24 修正数据为0的错误，修正网页不显示<>符号。
• 2016-02-02 增加IOS HTTP请求代码生成，增加请求固定参数FinalElement，增加请求本地缓存开关。修复Java代码引用包java.util.List。

代码示例：

工具介绍：

• 简单的说就是让终端人员不用看你的写的API文档，直接拿生成好的解析代码到项目，快精准。

CSDN代码地址      GIT地址       演示地址

PS：GIT版本为开发调试版本，不能保证其稳定。CSDN的版本为GIT上封装完最稳定的版本，请斟酌下载。

效果图：

• 
  

输出支持：

• TXT文档
• JAVA （代码需要依赖第三方包，详见Android快速SDK（5）联网请求库QuickHttp）
• JAVANATIVE（android原生代码，下载导入项目即可使用）
• SWIFT（swift原生代码，下载导入项目即可使用）
• IOS（代码需要依赖第三方解析包，详见MJExtension）

解决问题：

• 免手写Word文档来告知第三人此API输出的内容字段含义以及需要哪些接收参数，降低沟通成本
• 每次API升级，输出内容都会打上版本号以及终端文件。只要在终端项目里面，GIT或者SVN即能看出本次升级更改的内容
• 与终端对接API接口调试，成功率提升到100%
• 终端无需理会数据接口，只需要把大部分的精力用在UI界面上

功能介绍：

• 输出Txt格式的文档
• 输出android端所需要的数据解析类以及数据请求类
• 输出ios端所需要的数据解析类
• 输出的数据类，包含原生系统自带的解析方式与第三方自动序列化方式（如：GSON）
• 针对未注释字段，自动英汉翻译
• 自动转换PHP输出json字段类型，由通用字符串类型自动归类（Int，Float，Long，String，Boolean）
• 终端语言模板化，可自行更改终端语言输出模板
• 自动根据字典文件的最后修改日期转换为终端语言文件的版本号，如

• /**
   * push信息表
   * @version 20151105.20.39
   * @author HuangYi
   * @link email：[email protected]
   * */
  public class PushInfoData {

  
  
• 
  

配置文件Config.php：

• 翻译设置（目前是接入百度翻译，需要自行去注册一个KEY）

• //百度翻译KEY
  define("BAIDU_LANGUAGE_APPKEY", "6e87261cf9d883ddc2bc4c629991a087");
  //启动翻译模式
  define("OPEN_LANGUAGE_MODE", true);
  //翻译过滤字段,简单说就是过滤那些一看就明白意思的字段
  define("AZ_LANGUAGE_FILTER", "{id}{date}{clientdate}{sex}");

  
  
• JAVA设置，路径的设置是为了让终端开发者直接以文件夹形式下载所有接口文件

• //JAVA包名
  define("JAVA_PACKNAME", "yousi.com.http.data");
  //JAVA数据类保存路径
  define("JAVA_DATA_SAVE_PATH", "/java/yousi/com/http/data/");
  //JAVA HTTP包名
  define("JAVA_HTTP_PACKNAME", "yousi.com.http");
  // JAVA请求数据类保存路径
  define("JAVA_HTTP_DATA_SAVE_PATH", "/java/yousi/com/http/");

  
  
• JAVANATIVE设置，路径的设置是为了让终端开发者直接以文件夹形式下载所有接口文件

• //JAVA原生数据类保存路径
  define("JAVA_NATIVE_DATA_SAVE_PATH", "/javanative/yousi/com/http/data/");
  // JAVA原生请求数据类保存路径
  define("JAVA_NATIVE_HTTP_DATA_SAVE_PATH", "/javanative/yousi/com/http/");
  

  
  
• TXT设置，路径的设置是为了让终端开发者直接以文件夹形式下载所有接口文件

• //TXT数据类保存路径
  define("TXT_DATA_SAVE_PATH", "/txt/http/data/");
  //TXT请求数据类保存路径
  define("TXT_HTTP_DATA_SAVE_PATH", "/txt/http/");

  
  
• IOS设置，路径的设置是为了让终端开发者直接以文件夹形式下载所有接口文件

• //IOS数据类保存路径
  define("IOS_DATA_SAVE_PATH", "/ios/yousi/com/http/data/");
  //IOS请求数据类保存路径
  define("IOS_HTTP_DATA_SAVE_PATH", "/ios/yousi/com/http/");

  
  
• SWIFT设置，路径的设置是为了让终端开发者直接以文件夹形式下载所有接口文件

• //SWIFT数据类保存路径
  define("SWIFT_DATA_SAVE_PATH", "/swift/http/data/");
  //SWIFT请求数据类保存路径
  define("SWIFT_HTTP_DATA_SAVE_PATH", "/swift/http/");

  
  

SDK接入：

• /**引用类路径*/
  include_once(dirname(__FILE__)."/../document_sdk/Element.php");
  
  /**以下为API接口测试数据*/
  $pinfo = array();
  $pinfo['id']=2;
  $pinfo['uid']='10086';
  $pinfo['rid']='10086';
  $pinfo['money']=100.25;
  $pinfo['key']='tokendddsxsedfs115';
  $pinfo['alias']='techer';
  $pinfo['aliastype']='yousi.com';
  $pinfo['date']='2015-11-12 15:17:23';
  $pinfo['clientdate']=1446450068;
  $pinfo['info']=$info;
  $pinfo['grade']=$grade;
  $pinfo['comments']=$comments;
  $pinfo['userinfo']=$userinfo;
  
  /**测试地址 Example.php?document=truxish2114558de&parse=java*/
  /**<在输出JSON API接口前面添加以下语句*/
  document($pinfo,'PushInfoData');
  
  /**输出JSON格式*/
  Json::echoJson($pinfo);

  
  
  
• 必须在服务器上设置自定义文件夹权限为777，因为输出的代码均在这个文件夹下。

  • //设置文档存放路径,且此目录文件夹必须具有777操作权限
    define("DOCUMENT_SAVE_ROOT_PATH", "/bbs/document");

    
    
• 设置秘钥，防止API接口文档外泄。

  • //API内部加密KEY，防止文档外泄
    define("DOCUMENT_KEY", "truxish2114558de");

    
    
• 其中接口转换文档参数
  • document为请求秘钥，自行更改，加密作用。
    
  • parse为转换类型，目前支持java，javanative，swift，txt，ios格式。
    
  • azauto为英汉翻译开关，true开启，false关闭。
    
• PushInfoData参数实为Class.PushInfoData.php简参，JSON输出数据解析字典
  
  • 字典元素分类
  1. key=>注释，此用来标示普通字段

     • /**API数据片段*/
       $pinfo['rid']='101';
       
       
       /**对应字典写法*/
       "rid"=>"回复ID"

     • 对应输出的JAVA代码片段
       
       /** 回复ID */ 
       public int rid = 0; 

       
       
  2. key=>array()，此用来标示数组元素又是数组，如

     • /**API数据片段*/
       $comment_data = array();
       $comment_data['uid'] = 10086;
       $comment_data['name'] = "大帅";
       //无论是多维数数组，只需写一个维度的字典
       $comments = array($comment_data,$comment_data);
       
       $pinfo['comments']=$comments;
       
       
        /**对应字典写法*/
       $comments_keys =array("uid"=>"用户账号","name"=>"昵称");
       $keys['comments'] = $comments_keys;

       
       

     • 对应输出的JAVA代码片段，从下面看出Comments 类本身没有注释
        	/** */ 
         	public class Comments { 
           	/** 用户账号 */ 
           	public int uid = 0; 
           	/** 昵称 */ 
           	public String name = ""; 
           	public Comments getBase(Context mContext, JSONObject jsonObject) { 
             	Comments mBase = new Comments(); 
             	try { 
               	mBase.uid = HttpBase.jsonToInt(jsonObject, "uid"); 
               	mBase.name = HttpBase.jsonToString(jsonObject, "name"); 
             	} catch (Exception e) { 
               	e.printStackTrace(); 
               	MyLog.d(RerviceHttp.class, "Comments error e:"+e.getMessage()); 
             	} 
             	return mBase; 
           	} 
         	} 

       
       
       
  3. key=>array(key=>array())，此用来解决第2条输出代码片段没有注释，如

     • /**API数据片段*/
       $info = array();
       $info['up'] =1;
       $info['down'] =1;
       
       $pinfo['info']=$info;
       
       
       /**对应字典写法*/
       $info_keys = array("基础信息" => array("up"=>"支持数","down"=>"反对数"));
       $keys["info"]=>$info_keys
       

       
       

     • 对应输出的JAVA代码片段，从下面看出类名为key本身
       	/** 基础信息 */ 
         	public Info info = new Info(); 
         	/** 基础信息 */ 
         	public class Info { 
           	/** 支持数 */ 
           	public int up = 0; 
           	/** 反对数 */ 
           	public int down = 0; 
           	public Info getBase(Context mContext, JSONObject jsonObject) { 
             	Info mBase = new Info(); 
             	try { 
               	mBase.up = HttpBase.jsonToInt(jsonObject, "up"); 
               	mBase.down = HttpBase.jsonToInt(jsonObject, "down"); 
             	} catch (Exception e) { 
               	e.printStackTrace(); 
               	MyLog.d(RerviceHttp.class, "Info error e:"+e.getMessage()); 
             	} 
             	return mBase; 
           	} 
         	}

  4. ClassElement指定类名元素，此用来解决第3条指定类名，如

     • /**API数据片段*/
       $info = array();
       $info['up'] =1;
       $info['down'] =1;
       
       $pinfo['info']=$info;
       
       
       /**对应字典写法*/
       $info_keys = array("基础信息" => array("up"=>"支持数","down"=>"反对数"));
       $info_keys = new ClassElement("InfoData",$info_keys);
       $keys["info"]=>$info_keys

       
       

     • 对应输出的JAVA代码片段
               /** 基础信息 */ 
         	public InfoData info = new InfoData(); 
         	/** 基础信息 */ 
         	public class InfoData { 
           	/** 支持数 */ 
           	public int up = 0; 
           	/** 反对数 */ 
           	public int down = 0; 
           	public InfoData getBase(Context mContext, JSONObject jsonObject) { 
             	InfoData mBase = new InfoData(); 
             	try { 
               	mBase.up = HttpBase.jsonToInt(jsonObject, "up"); 
               	mBase.down = HttpBase.jsonToInt(jsonObject, "down"); 
             	} catch (Exception e) { 
               	e.printStackTrace(); 
               	MyLog.d(RerviceHttp.class, "InfoData error e:"+e.getMessage()); 
             	} 
             	return mBase; 
           	} 
         	} 

       
       
  5. NoteElement指定元素类型，将不会在自动归类，如

     • /**API数据片段*/
       $pinfo['uid']='10086';
       
       
       /**对应字典写法*/
       $uid_keys = new NoteElement("用户UID",Element::TYPE_KEY_STRING);
       $keys["uid"]=>$uid_keys

       
       

     • 对应输出的JAVA代码片段，从下面看出uid自动归类应为Int类型，但强制为String类型
       /** 用户UID */ 
       public String uid = ""; 

     
     
  6. RangeElement静态常量元素类型，通用用于解释数值取值范围，如：
     
     • 请求参数数值范围

     • /**对应请求参数字典写法*/
       $type = new RangeElement(array("list"=>"列表","info"=>"详情"),"类型");
       $keys['type'] = $type;

     • 对应输出的JAVA请求类代码片段
       /** 列表 */ 
       public static final String TYPE_TYPE_LIST = "list"; 
       /** 详情 */ 
       public static final String TYPE_TYPE_INFO = "info"; 

       
       
     • 返回结果数值解释

     • /**对应字典写法*/
       $sex = new RangeElement(array("男","女","不限"),"性别");
       $keys['sex'] = $sex;

     • 对应JAVA输出代码片段
       /** 男 */ 
       public static final int SEX_0 = 0; 
       /** 女 */ 
       public static final int SEX_1 = 1; 
       /** 不限 */ 
       public static final int SEX_2 = 2; 
       
       /** 性别 */ 
       public int sex = 0; 

  7. FinalElement固定值请求参数，如

     • 	/**请求参数*/
       	function getHttpKeys(){
       
       		$type = new FinalElement("ar_result","识别点");
       		$api = new FinalElement("json","客户端请求");
       		$keys = array(	"api" => $api,
       						"type"=>$type,
       						"dbid"=>"0或不写，则获取整个产品所有的库包",
       						"appkey"=>"产品KEY"
       						#
       		);
       		return $keys;
       	}

     • 
       
       
       

FileElement指定请求参数为文件上传，如

• /**对应请求参数字典写法*/
  $file = new FileElement("文件上传");
  $keys['file'] = $file;

• 对应输出的JAVA代码片段
    	/** 文件上传 */ 
    	public Map mUploadFile = new HashMap(); 
  
    	public void setfilePath(String mPath) { 
      	setPath("file", mPath); 
    	} 
  
    	private void setPath(String mKey, String mPath) { 
      	mUploadFile.put(mKey, new File(mPath)); 
    	} 
  
    	@Override 
    	public Map getSendFile() { 
      	if (mUploadFile == null || mUploadFile.size() <= 0) { 
        	return new HashMap(); 
      	} 
      	return mUploadFile; 
    	}