本排版示例整理于兩年前，當時是用來在公司推廣使用 Markdown 編寫開發(fā)文檔的，現(xiàn)在稍微作了些修改，去掉一些與公司接口相關的信息。希望該示例能夠對小伙伴們在以后編寫文檔時有所幫助，也希望能夠得到大家關于文檔排版方面的建議。
使用 Markdown 編寫接口文檔最主要的好處，一個是可以讓你更專注于內容本身，另外一個是 Markdown編寫的文檔能用代碼管理工具（Git、SVN等）進行有效的版本管理（如版本對比）。

本示例顯示效果如下：（源文件鏈接：https://github.com/iuiuu/markdown-api-document）

AA公司BC平臺接口文檔 v3.2.0

1 規(guī)范說明

1.1 通信協(xié)議

HTTPS協(xié)議

1.2 請求方法

所有接口只支持POST方法發(fā)起請求。

1.3 字符編碼

HTTP通訊及報文BASE64編碼均采用UTF-8字符集編碼格式。

1.4 格式說明

元素出現(xiàn)要求說明：

1.5 報文規(guī)范說明

1. 報文規(guī)范僅針對交易請求數(shù)據(jù)進行描述；

2. 報文規(guī)范中請求報文的內容為Https請求報文中RequestData值的明文內容；

3. 報文規(guī)范分為請求報文和響應報文。請求報文描述由發(fā)起方，響應報文由報文接收方響應。

1.6 請求報文結構

接口只接收兩個參數(shù) RequestData 和 SignData ，其中RequestData的值為請求內容，SignData的值為簽名內容。

1.6.1 參數(shù)說明

RequestData（請求內容）： 其明文為每次請求的具體參數(shù)，采用 JSON 格式，依次經過 DES 加密（以UTF-8編碼、BASE64編碼輸出結果）和 URLEncode 后，作為 RequestData 的值。

SignData（簽名內容）： 請求參數(shù)（明文）的MD5加密字符串，用于校驗RequestData是否合法。

1.6.2 請求內容（RequestData）明文結構說明

采用JSON格式，其中包含Header（公有參數(shù)）、Body（私有參數(shù)）節(jié)點：

公共參數(shù)說明：

公共參數(shù)（Header）是用于標識產品及接口鑒權的參數(shù)，每次請求均需要攜帶這些參數(shù)：

1.6.3 校驗流程：

服務端接收到請求后首先對RequestData進行DES解密出JSON字符串，然后對JSON字符串進行MD5加密，加密后的值與請求中的SignData值進行對比，如對比通過，視為合法請求，否則視為非法請求。

DES加密/解密函數(shù)示例：

C#版：

/// <summary>
/// 進行DES加密。
/// </summary>
/// <param name="decryptString">要加密的字符串。</param>
/// <param name="secretKey">密鑰，且必須為8位。</param>
/// <returns>以Base64格式返回的加密字符串。</returns>
public static string DesEncrypt(string decryptString, string secretKey)
{
    using (DESCryptoServiceProvider des = new DESCryptoServiceProvider())
    {
        byte[] inputByteArray = Encoding.UTF8.GetBytes(decryptString);
        des.Key = Encoding.ASCII.GetBytes(secretKey);
        des.IV = Encoding.ASCII.GetBytes(secretKey);
        MemoryStream ms = new MemoryStream();
        using (CryptoStream cs = new CryptoStream(ms, des.CreateEncryptor(), CryptoStreamMode.Write))
        {
            cs.Write(inputByteArray, 0, inputByteArray.Length);
            cs.FlushFinalBlock();
            cs.Close();
        }
        string str = Convert.ToBase64String(ms.ToArray());
        ms.Close();
        return str;
    }
}

/// <summary>
/// 進行DES解密。
/// </summary>
/// <param name="encryptedString">要解密的以Base64</param>
/// <param name="secretKey">密鑰，且必須為8位。</param>
/// <returns>已解密的字符串。</returns>
public static string DesDecrypt(string encryptedString, string secretKey)
{
    byte[] inputByteArray = Convert.FromBase64String(encryptedString);
    using (DESCryptoServiceProvider des = new DESCryptoServiceProvider())
    {
        des.Key = Encoding.ASCII.GetBytes(secretKey);
        des.IV = Encoding.ASCII.GetBytes(secretKey);
        MemoryStream ms = new MemoryStream();
        using (CryptoStream cs = new CryptoStream(ms, des.CreateDecryptor(), CryptoStreamMode.Write))
        {
            cs.Write(inputByteArray, 0, inputByteArray.Length);
            cs.FlushFinalBlock();
            cs.Close();
        }
        string str = Encoding.UTF8.GetString(ms.ToArray());
        ms.Close();
        return str;
    }
}

JAVA版：

/* DES解密 */
public static String decrypt(String message, String key) throws Exception {

    byte[] bytesrc = Base64.decode(message);
    //convertHexString(message);
    Cipher cipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
    DESKeySpec desKeySpec = new DESKeySpec(key.getBytes("UTF-8"));
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
    SecretKey secretKey = keyFactory.generateSecret(desKeySpec);
    IvParameterSpec iv = new IvParameterSpec(key.getBytes("UTF-8"));
    cipher.init(Cipher.DECRYPT_MODE, secretKey, iv);
    byte[] retByte = cipher.doFinal(bytesrc);
    return new String(retByte);
}


/* DES加密 */
public static byte[] encrypt(String message, String key) throws Exception {
    Cipher cipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
    DESKeySpec desKeySpec = new DESKeySpec(key.getBytes("UTF-8"));
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
    SecretKey secretKey = keyFactory.generateSecret(desKeySpec);
    IvParameterSpec iv = new IvParameterSpec(key.getBytes("UTF-8"));
    cipher.init(Cipher.ENCRYPT_MODE, secretKey, iv);
    return cipher.doFinal(message.getBytes("UTF-8"));
}

1.6.4 DES密鑰

測試環(huán)境：az2ih1uY

生產環(huán)境：另外提供。

1.6.5 請求報文示例

請求內容明文：

{
    "Header":{
        "Token":"2366CF921FAD44CCBB07FF9CD02FC90E",
        "Version":"3.2.0",
        "SystemId":100,
        "Timestamp":1502870664
    },
    "Body":{
        "Mobile":"18520322032",
        "Password":"acb000000"
    }
}

請求報文示例：

url?RequestData=UFAYIRF21XzGoaAaEU54qoDBYaFkT2KbRpWxKZuqqltApdIneF7AjlEArPLsg3%2Fo1Pu7FHFmsKZn%0A9KJb%2BGuwx0P%2F3jzv2TgwUpVtgwEdfd0vIRfqEF4jCouldaxxVBjbHvd%2F08pUoYJDNZJLvNrJ%2BsK4%0A79de92T0Cyu4hKNMUPtVI7Tp0IC%2BBw%3D%3D&SignData=0865c7d625f90d3bb5457f5d9ac3725d

1.7 響應報文結構

1.7.1 結構說明

所有接口響應均采用JSON格式，如無特殊說明，每次請求的返回值中，都包含下列字段：

1.7.2 響應報文示例

{
    "Code":200,
    "Msg":"調用成功",
    "Data":{
        "Channel":"A10086",
        "Type":7004
    }
}

2. 接口定義

2.1 密碼登錄

• 接口說明： 密碼登錄
• 接口地址： /account/signin

2.1.1 請求參數(shù)

請求示例：

{
    "Header":{
        "Token":"",
        "Version":"3.2.0",
        "SystemId":100,
        "Timestamp":1502870664
    },
    "Body":{
        "Mobile":"18520322032",
        "Password":"acb000000"
    }
}

2.1.2 返回結果

示例：

{
    "Code":200,
    "Msg":"登錄成功",
    "Data":{
        "UserId":"7D916C7283434955A235C17DD9B71C64"
    }
}

2.2 獲取登錄用戶信息

• 接口說明： 獲取登錄用戶信息
• 接口地址： /account/profile

2.2.1 請求參數(shù)

請求示例：

{
    "Header":{
        "Token":"CA64A439E7C344B0BA7F5C825E17C7AB",
        "Version":"3.2.0",
        "SystemId":100,
        "Timestamp":1502870664
    },
    "Body":null
}

2.2.2 返回結果

示例：

{
    "Code":200,
    "Msg":"處理成功",
    "Data":{
        "UserId":"7D916C7283434955A235C17DD9B71C64",
        "RealName":"張三",
        "ImageUrl":"https://img.xx.net/afdicew8751.png",
        "Score":4732,
        "Nickname":"張冠李戴",
        "Sex":1,
        "Title":"俠客Lv4"
    }
}

3 附錄A 響應碼說明

4 附錄B 幣種