技术文档的作用

1. 概述

• 在做项目的过程中，发现居然有人不知道技术文档的作用，以及如何写技术文档，可能因为所处环境的特殊，大家对基本的计算机知识都不是很懂吧！我查了一些资料，根据自己的理解，谈一谈技术文档吧！

2. 概念

• 技术文档：使用技术文档，主要也是为了加快团队之间的沟通，别人可以很好的理解你做的这些模块的功能。帮助别人在不需要理解你的代码的前提下，很方便的调用你的模块功能。

3. 示例

3.1 API接口文档

3.1.1 接口示例

资源信息接口

简要描述：

• 用户获取资源（游戏、视频）基本信息，利用基本信息可获得资源数据

请求URL：
- http://xx.com/search

请求方式：
- GET

参数：

参数名	必选	类型	说明
type	否	string	资源类型（game/video)
limit	否	int	搜索结果数量
item	否	string	资源标题关键字

返回示例

  {
    "resultCount": 2,
    "results": 
    [{
      "id": "db8b9f7f0ca4d269927dc0e9b78fd0f8",
      "kind": "video",
      "title": "apple",
      "info": "视频介绍" ,
      "previewTitle":"预览图名",
      "releaseDate":"2000-09-26 07:00:00",
      "trackTimeMillis":211600,
      "sourceUrl":"192.168.3.100\/videoSource\/"
     }
  }

返回参数说明

参数名	类型	说明
id	int	资源ID
kind	string	资源种类（game/video）
title	string	资源名称
info	string	资源基本介绍
previewTitle	string	资源图标名称
releaseDate	string	资源发布时间
trackTimeMillis	bigint	视频长度（单位：s)
sourceUrl	string	文件资源（图标、截图等）的路径

3.1.2 说明

• 通过该接口，前端人员边可以很方便的了解了后台接口需要提交什么请求，能够获得什么数据，才可以根据后台提供的数据进行整合，把后台提供的原材料煮成一道道菜出来。

3.2 Android平台SDK文档

3.2.1 文档示例

这是微博的SDK文档中分享微博功能实现的说明文档。
1) 分享前准备工作
在进行微博分享前，需要在AndroidManifest.xml中，在需要接收消息的Activity（唤起微博主程序的类）里声明对应的Action：ACTION_SDK_REQ_ACTIVITY，如下所示：

<activity
    android:name="com.sina.weibo.sdk.demo.WBShareActivity"
    android:configChanges="keyboardHidden|orientation"
    android:screenOrientation="portrait" >
    <intent-filter>
            <action android:name="com.sina.weibo.sdk.action.ACTION_SDK_REQ_ACTIVITY" />
            <category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
<activity 
     android:name="com.sina.weibo.sdk.component.WeiboSdkBrowser" 
     android:configChanges="keyboardHidden|orientation"
     android:windowSoftInputMode="adjustResize"
     android:exported="false" >
</activity>

2) 分享实现
① 在onCreate函数创建微博分享接口实例，并进行注册，请确保先注册，后分享

mWeiboShareAPI = WeiboShareSDK.createWeiboAPI(this, Constants.APP_KEY);
mWeiboShareAPI.registerApp();   // 将应用注册到微博客户端

② 创建要分享的内容

private TextObject getTextObj() {
    TextObject textObject = new TextObject();
    textObject.text = getSharedText();
    return textObject;
}

③ 通过IWeiboShareAPI#sendRequest唤起微博客户端发博器进行分享

private void sendMultiMessage(boolean hasText, boolean hasImage, boolean hasWebpage,
        boolean hasMusic, boolean hasVideo, boolean hasVoice) {
    WeiboMultiMessage weiboMessage = new WeiboMultiMessage();//初始化微博的分享消息
    if (hasText) {
        weiboMessage. textObject = getTextObj();
    }
    SendMultiMessageToWeiboRequest request = new SendMultiMessageToWeiboRequest();
    request.transaction = String.valueOf(System.currentTimeMillis());
    request.multiMessage = weiboMessage;
    mWeiboShareAPI.sendRequest(request); //发送请求消息到微博，唤起微博分享界面
}

④ 实现IWeiboHandler#Response接口，接收分享后微博返回的数据

protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    mWeiboShareAPI.handleWeiboResponse(intent, this); //当前应用唤起微博分享后，返回当前应用
}
@Override
public void onResponse(BaseResponse baseResp) {//接收微客户端博请求的数据。
    switch (baseResp.errCode) {
    case WBConstants.ErrorCode.ERR_OK:      .........
        break;
    case WBConstants.ErrorCode.ERR_CANCEL: .........
        break;
    case WBConstants.ErrorCode.ERR_FAIL:    .........
        break;
    }
}

3.2.2 说明

• 微博的SDK文档中通过实例详细的介绍了每个接口如何实现，用户仅需将SDK导入到项目中，通过这些说明步骤，便可以很方便的使用SDK提供的功能，而不需要了解其内部具体是怎么实现的，即封装性。

参考资料

• 微博Android平台SDK文档