|
|
|
package com.yoho.search.service.restapi;
|
|
|
|
|
|
|
|
import com.yoho.search.base.utils.FileUtils;
|
|
|
|
import org.apache.commons.lang3.StringUtils;
|
|
|
|
|
|
|
|
import java.util.HashMap;
|
|
|
|
import java.util.Map;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Created by ginozhang on 2016/11/17.
|
|
|
|
*/
|
|
|
|
public class MarkDownUtils {
|
|
|
|
|
|
|
|
private final String SEPARATOR = System.getProperty("line.separator");
|
|
|
|
|
|
|
|
private Map<String, String> typeDescptions = new HashMap<>();
|
|
|
|
|
|
|
|
private String api;
|
|
|
|
|
|
|
|
private MarkDownUtils(String api) {
|
|
|
|
this.api = api;
|
|
|
|
}
|
|
|
|
|
|
|
|
public static MarkDownUtils getInstance(String api) {
|
|
|
|
return new MarkDownUtils(api);
|
|
|
|
}
|
|
|
|
|
|
|
|
{
|
|
|
|
typeDescptions.put("connected_int", "int多值参数类型，多个值用逗号分隔。");
|
|
|
|
typeDescptions.put("ranged_double", "double范围类型，使用逗号分隔下限和上限");
|
|
|
|
typeDescptions.put("ranged_int", "int范围类型，使用逗号分隔下限和上限");
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 根据接口描述文件生成接口描述的MD文件
|
|
|
|
*/
|
|
|
|
public void generateApiMd() {
|
|
|
|
Map<String, Object> apiDef = ApiDefUtils.getApiDef(api);
|
|
|
|
StringBuffer sb = new StringBuffer(500);
|
|
|
|
sb.append("# ").append(api).append(" 接口说明").append(SEPARATOR);
|
|
|
|
|
|
|
|
// 1. 生成header 秒杀接口的功能和使用场景
|
|
|
|
sb.append(apiDef.get("_name")).append(SEPARATOR);
|
|
|
|
|
|
|
|
// 2. 生成请求参数说明
|
|
|
|
sb.append(getRequestMdTable(apiDef));
|
|
|
|
|
|
|
|
// 3. 生成响应参数说明
|
|
|
|
sb.append(generateResponseMdTable(apiDef));
|
|
|
|
|
|
|
|
FileUtils.writeFile("test.md", sb.toString());
|
|
|
|
}
|
|
|
|
|
|
|
|
private StringBuffer generateResponseMdTable(Map<String, Object> apiDef) {
|
|
|
|
return generateMdTable4SingleObject(api + " 响应参数说明", (Map<String, Object>) apiDef.get("_response"), 2);
|
|
|
|
}
|
|
|
|
|
|
|
|
private StringBuffer generateMdTable4SingleObject(String tableTitle, Map<String, Object> respnseDef, int level) {
|
|
|
|
StringBuffer sb = new StringBuffer(100);
|
|
|
|
sb.append(getLevelChars(level)).append(tableTitle).append(SEPARATOR);
|
|
|
|
sb.append("|参数名 |参数类型 |参数说明 |").append(SEPARATOR);
|
|
|
|
sb.append("|------|--------|---------|").append(SEPARATOR);
|
|
|
|
for (Map.Entry<String, Object> entry : respnseDef.entrySet()) {
|
|
|
|
String paramName = entry.getKey();
|
|
|
|
Map<String, Object> details = ((Map<String, Object>) entry.getValue());
|
|
|
|
String type = getTypeDescription((String) details.get("_type"));
|
|
|
|
String desc = (String) details.get("_desc");
|
|
|
|
sb.append("|").append(paramName).append("|").append(type).append("|").append(desc).append("|").append(SEPARATOR);
|
|
|
|
|
|
|
|
if ("object".equals(type) || "array".equals(type)) {
|
|
|
|
// 如果是数组或者对象类型 就新搞一个表格来说明里面的对象
|
|
|
|
sb.append(SEPARATOR).append(SEPARATOR);
|
|
|
|
sb.append(generateMdTable4SingleObject("参数" + paramName + "的属性说明", (Map<String, Object>) details.get("_content"), level + 1));
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
sb.append(SEPARATOR).append(SEPARATOR);
|
|
|
|
return sb;
|
|
|
|
}
|
|
|
|
|
|
|
|
private StringBuffer getRequestMdTable(Map<String, Object> apiDef) {
|
|
|
|
StringBuffer sb = new StringBuffer(100);
|
|
|
|
sb.append("## ").append(api).append(" 请求参数说明").append(SEPARATOR);
|
|
|
|
sb.append("|参数名 |参数类型 |参数说明 |").append(SEPARATOR);
|
|
|
|
sb.append("|------|--------|---------|").append(SEPARATOR);
|
|
|
|
|
|
|
|
Map<String, Object> requestDef = (Map<String, Object>) apiDef.get("_request");
|
|
|
|
for (Map.Entry<String, Object> entry : requestDef.entrySet()) {
|
|
|
|
String paramName = entry.getKey();
|
|
|
|
Map<String, String> details = ((Map<String, String>) entry.getValue());
|
|
|
|
String type = getTypeDescription(details.get("_type"));
|
|
|
|
String desc = details.get("_desc");
|
|
|
|
sb.append("|").append(paramName).append("|").append(type).append("|").append(desc).append("|").append(SEPARATOR);
|
|
|
|
}
|
|
|
|
sb.append(SEPARATOR).append(SEPARATOR);
|
|
|
|
return sb;
|
|
|
|
}
|
|
|
|
|
|
|
|
private StringBuffer getLevelChars(int level) {
|
|
|
|
StringBuffer sb = new StringBuffer(10);
|
|
|
|
level = level <= 3 ? level : 3;
|
|
|
|
for (int i = 1; i <= level; i++) {
|
|
|
|
sb.append("#");
|
|
|
|
}
|
|
|
|
|
|
|
|
sb.append(" ");
|
|
|
|
return sb;
|
|
|
|
}
|
|
|
|
|
|
|
|
private String getTypeDescription(String type) {
|
|
|
|
|
|
|
|
if (StringUtils.isEmpty(type)) {
|
|
|
|
type = "string";
|
|
|
|
}
|
|
|
|
|
|
|
|
if (typeDescptions.containsKey(type)) {
|
|
|
|
return typeDescptions.get(type);
|
|
|
|
}
|
|
|
|
|
|
|
|
if (type.startsWith("enum_")) {
|
|
|
|
String enumKey = type.substring("enum_".length());
|
|
|
|
return "枚举类型，可选范围：" + ApiDefUtils.getEnumItems(api, enumKey);
|
|
|
|
} else if (type.startsWith("connected_enum_")) {
|
|
|
|
String enumKey = type.substring("connected_enum_".length());
|
|
|
|
return "多值枚举类型，枚举可选范围：" + ApiDefUtils.getEnumItems(api, enumKey) + ", 多个值用逗号分隔。";
|
|
|
|
} else if (type.startsWith("optional")) {
|
|
|
|
String specialValue = type.substring("optional(".length(), "optional(".length() + 1);
|
|
|
|
return "特定值{" + specialValue + "}或不传值";
|
|
|
|
}
|
|
|
|
|
|
|
|
StringBuffer sb = new StringBuffer(type);
|
|
|
|
return sb.toString();
|
|
|
|
}
|
|
|
|
|
|
|
|
} |
...
|
...
|
|
