技术文档的作用

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文档