用Markdown优雅地编写接口文档（排版示例）

本排版示例整理于两年前，当时是用来在公司推广使用 Markdown 编写开发文档的，现在稍微作了些修改，去掉一些与公司接口相关的信息。希望该示例能够对小伙伴们在以后编写文档时有所帮助，也希望能够得到大家关于文档排版方面的建议。
使用 Markdown 编写接口文档最主要的好处，一个是可以让你更专注于内容本身，另外一个是 Markdown编写的文档能用代码管理工具（Git、SVN等）进行有效的版本管理（如版本对比）。

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

AA公司BC平台接口文档 v3.2.0

1 规范说明

1.1 通信协议

HTTPS协议

1.2 请求方法

所有接口只支持POST方法发起请求。

1.3 字符编码

HTTP通讯及报文BASE64编码均采用UTF-8字符集编码格式。

1.4 格式说明

元素出现要求说明：

符号	说明
R	报文中该元素必须出现（Required）
O	报文中该元素可选出现（Optional）
C	报文中该元素在一定条件下出现（Conditional）

1.5 报文规范说明

报文规范仅针对交易请求数据进行描述；
报文规范中请求报文的内容为Https请求报文中RequestData值的明文内容；
报文规范分为请求报文和响应报文。请求报文描述由发起方，响应报文由报文接收方响应。

1.6 请求报文结构

接口只接收两个参数 RequestData 和 SignData ，其中RequestData的值为请求内容，SignData的值为签名内容。

1.6.1 参数说明

RequestData（请求内容）： 其明文为每次请求的具体参数，采用 JSON 格式，依次经过 DES 加密（以UTF-8编码、BASE64编码输出结果）和 URLEncode 后，作为 RequestData 的值。

SignData（签名内容）： 请求参数（明文）的MD5加密字符串，用于校验RequestData是否合法。

1.6.2 请求内容（RequestData）明文结构说明

采用JSON格式，其中包含Header（公有参数）、Body（私有参数）节点：

名称	描述	备注
公共参数	每个接口都包含的通用参数，以JSON格式存放在Header属性	详见以下公共参数说明
私有参数	每个接口特有的参数，以JSON格式存放在Body属性	详见每个接口定义

公共参数说明：

公共参数（Header）是用于标识产品及接口鉴权的参数，每次请求均需要携带这些参数：

参数名称	类型	出现要求	描述
Token	string	R	用户登录后token，没有登录则为空字符串
Version	string	R	接口版本号
SystemId	int	R	机构号，请求的系统Id
Timestamp	long	R	当前UNIX时间戳

1.6.3 校验流程：

服务端接收到请求后首先对RequestData进行DES解密出JSON字符串，然后对JSON字符串进行MD5加密，加密后的值与请求中的SignData值进行对比，如对比通过，视为合法请求，否则视为非法请求。

DES加密/解密函数示例：

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密钥

测试环境：az2ih1uY

生产环境：另外提供。

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格式，如无特殊说明，每次请求的返回值中，都包含下列字段：

参数名称	类型	出现要求	描述
Code	int	R	响应码，代码定义请见“附录A 响应吗说明”
Msg	string	R	响应描述
Data	object	R	每个接口特有的参数，详见每个接口定义

1.7.2 响应报文示例

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

2. 接口定义

2.1 密码登录

接口说明： 密码登录
接口地址： /account/signin

2.1.1 请求参数

参数名称	类型	出现要求	描述
Header		R	请求报文头
Token	string	R	用户登录后token，没有登录则为空字符串
Version	string	R	接口版本号
SystemId	int	R	机构号，请求的系统Id
Timestamp	long	R	当前UNIX时间戳
Body		R
Mobile	string	R	手机号
Password	string	R	密码

请求示例：

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

2.1.2 返回结果

参数名称	类型	出现要求	描述
Code	int	R	响应码，代码定义请见“附录A 响应吗说明”
Msg	string	R
Data	object	R
UserId	string	R	用户Id

示例：

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

2.2 获取登录用户信息

接口说明： 获取登录用户信息
接口地址： /account/profile

2.2.1 请求参数

参数名称	类型	出现要求	描述
Header		R	请求报文头
Token	string	R	用户登录后token，没有登录则为空字符串
Version	string	R	接口版本号
SystemId	int	R	机构号，请求的系统Id
Timestamp	long	R	当前UNIX时间戳
Body		R