接口文档编写规范

下载标准API文档示例

1. 插件文档说明

插件文档是对插件功能的详细说明。 插件文档编写分为两个部分：插件文档和插件接口文档。 插件文档分为两个部分：插件介绍和API列表。 插件接口文档分为三个部分：方法介绍、参数说明和示例代码（示例代码里面可以添加“响应示例代码”）。

2.插件文档

2.1 插件介绍

包括两部分：

1.插件功能描述

例如：集成微信的登录和分享功能

2.插件注意事项 例如：

[!WARNING]

• 插件的所有接口在 deviceready 事件后生效;
• 使用插件需配置:AppID;

2.2 API列表

包括两部分：API和说明

API是指此插件提供的方法。说明是当前方法的注释说明。

例如：

3.插件接口文档

3.1 方法介绍

例如： 微信登录

[!TIP|labelVisibility:hidden|iconVisibility:hidden] navigator.wechat.getAuth(successCallback, errorCallback)

支持平台：

• Android
• iOS

3.2 参数说明

例如：

successCallback函数会返回授权成功个人信息，包含以下属性:

• openid( String ) -- 普通用户的标识，对当前开发者帐号唯一
• city( String ) -- 普通用户个人资料填写的城市
• province( String ) -- 普通用户个人资料填写的省份
• country( String ) -- 国家，如中国为CN
• nickname( String ) -- 普通用户昵称
• privilege( Array ) -- 用户特权信息，json数组，如微信沃卡用户为（chinaunicom）
• language( String ) -- 国家地区语言版本，zh_CN简体，zh_TW繁体，en英语，默认为zh_CN
• headimgurl( String ) -- 用户微信头像
• unionid( String ) -- 用户统一标识。针对一个微信开放平台帐号下的应用，同一用户的unionid是唯一的。
• sex( Number ) -- 普通用户性别，1 为男性，2 为女性

errorCallback函数会返回一个字符串，登录错误的相关信息

3.3 示例代码

例如：

// 引用js
<script src='supconit://hcmobile.js'></script>
<script>
    // 监听’deviceready‘事件
    document.addEventListener('deviceready', onDeviceReady, false)
    function onDeviceReady(){
        // 登录 
        navigator.wechat.getAuth(function (successCallback) {
          alert(JSON.stringify(successCallback));
        },function (errorCallback) {
          alert(JSON.stringify(errorCallback));
        }
        )
    }
</script>

响应示例代码：

{
    "openid": "ojCmnt**",
    "city": "",
    "country": "",
    "nickname": "liu**",
    "privilege": [],
    "language": "zh_CN",
    "headimgurl": "http://thirdwx**",
    "sex": 0,
    "province": ""
}

4.插件文档模板

a插件

集成a插件功能

[!WARNING]

• 插件的所有接口在 deviceready 事件后生效;
• ...

API列表

1.a表示插件名称

2.method1表示方法名

5.插件接口文档模板

[!TIP|labelVisibility:hidden|iconVisibility:hidden] navigator.a.method1(para, success, error)

支持平台：

• Android
• iOS

参数说明

success函数返回数据，例如："函数返回一个字符串，成功的相关信息"

error函数会返回数据，例如："函数返回一个字符串，失败的相关信息"

示例代码

// 引用js
<script src='supconit://hcmobile.js'></script>
<script>
    // 监听’deviceready‘事件
    document.addEventListener('deviceready', onDeviceReady, false)
    function onDeviceReady(){
        navigator.a.method1('111',function (success) {
            console.log(success);
        },function (error) {
            console.log(error);
        });
    }
</script>

1.a表示插件名称

2.method1表示方法名

3.para表示参数，支持多种类型：Object、Array、String，具体书写方式参考插件文档()