diff --git a/src/main/java/com/power/doc/builder/ApiDocBuilder.java b/src/main/java/com/power/doc/builder/ApiDocBuilder.java index 47fd136..cd6e7f8 100644 --- a/src/main/java/com/power/doc/builder/ApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/ApiDocBuilder.java @@ -25,10 +25,10 @@ import static com.power.doc.constants.DocGlobalConstants.*; public class ApiDocBuilder { /** - * 生成所有controller的api文档 - * - * @param outPath 代码输出路径 - * @param isStrict 是否启用严格模式 + * Generate api documentation for all controllers. + * If set to strict mode, smart-doc will check the method comments on each controller. + * @param outPath output path + * @param isStrict is use strict mode */ public static void builderControllersApi(String outPath, boolean isStrict) { SourceBuilder sourceBuilder = new SourceBuilder(isStrict); @@ -37,7 +37,7 @@ public class ApiDocBuilder { } /** - * @param config 配置 + * @param config ApiConfig */ public static void builderControllersApi(ApiConfig config) { if (null == config) { @@ -63,10 +63,10 @@ public class ApiDocBuilder { } /** - * 生成单个controller的api文档 + * Generate a single controller api document * - * @param outPath 代码输出路径 - * @param controllerName controller 名称 + * @param outPath output path + * @param controllerName controller name */ public static void buildSingleControllerApi(String outPath, String controllerName) { FileUtil.mkdirs(outPath); @@ -75,15 +75,15 @@ public class ApiDocBuilder { Template mapper = BeetlTemplateUtil.getByName(API_DOC_TPL); mapper.binding(TemplateVariable.DESC.getVariable(), doc.getDesc()); mapper.binding(TemplateVariable.NAME.getVariable(), doc.getName()); - mapper.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名 + mapper.binding(TemplateVariable.LIST.getVariable(), doc.getList()); FileUtil.writeFileNotAppend(mapper.render(), outPath + FILE_SEPARATOR + doc.getName() + "Api.md"); } /** - * 公共生成controller api 文档 + * Generate api documentation for all controllers. * - * @param apiDocList - * @param outPath + * @param apiDocList list of api doc + * @param outPath output path */ private static void buildApiDoc(List apiDocList, String outPath) { FileUtil.mkdirs(outPath); @@ -91,13 +91,13 @@ public class ApiDocBuilder { Template mapper = BeetlTemplateUtil.getByName(API_DOC_TPL); mapper.binding(TemplateVariable.DESC.getVariable(), doc.getDesc()); mapper.binding(TemplateVariable.NAME.getVariable(), doc.getName()); - mapper.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名 + mapper.binding(TemplateVariable.LIST.getVariable(), doc.getList()); FileUtil.nioWriteFile(mapper.render(), outPath + FILE_SEPARATOR + doc.getName() + "Api.md"); } } /** - * 合并所有接口文档到一个文档中 + * Merge all api doc into one document * * @param apiDocList */ @@ -113,15 +113,15 @@ public class ApiDocBuilder { } /** - * 构建错误码列表 + * build error_code html * - * @param errorCodeList 错误列表 + * @param errorCodeList list of error code * @param outPath */ private static void buildErrorCodeDoc(List errorCodeList, String outPath) { if (CollectionUtil.isNotEmpty(errorCodeList)) { Template mapper = BeetlTemplateUtil.getByName(ERROR_CODE_LIST_TPL); - mapper.binding(TemplateVariable.LIST.getVariable(), errorCodeList);//类名 + mapper.binding(TemplateVariable.LIST.getVariable(), errorCodeList); FileUtil.nioWriteFile(mapper.render(), outPath + FILE_SEPARATOR + ERROR_CODE_LIST_MD); } } diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index f8afee4..fe4c998 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -25,8 +25,10 @@ import static com.power.doc.constants.DocGlobalConstants.*; public class HtmlApiDocBuilder { private static long now = System.currentTimeMillis(); + /** - * @param config 配置 + * build controller api + * @param config config */ public static void builderControllersApi(ApiConfig config) { if (null == config) { @@ -56,6 +58,11 @@ public class HtmlApiDocBuilder { FileUtil.nioWriteFile(mdCssTemplate.render(), outPath + FILE_SEPARATOR + MARKDOWN_CSS_TPL); } + /** + * build api.html + * @param apiDocList list of api doc + * @param config ApiConfig + */ private static void buildIndex(List apiDocList, ApiConfig config) { FileUtil.mkdirs(config.getOutPath()); Template indexTemplate = BeetlTemplateUtil.getByName(INDEX_TPL); @@ -78,10 +85,10 @@ public class HtmlApiDocBuilder { /** - * 公共生成controller api 文档 + * build ever controller api * - * @param apiDocList - * @param outPath + * @param apiDocList list of api doc + * @param outPath output path */ private static void buildApiDoc(List apiDocList, String outPath) { FileUtil.mkdirs(outPath); @@ -104,15 +111,15 @@ public class HtmlApiDocBuilder { } /** - * 构建错误码列表 + * build error_code html * - * @param errorCodeList 错误列表 + * @param errorCodeList list of error code * @param outPath */ private static void buildErrorCodeDoc(List errorCodeList, String outPath) { if (CollectionUtil.isNotEmpty(errorCodeList)) { Template error = BeetlTemplateUtil.getByName(ERROR_CODE_LIST_TPL); - error.binding(TemplateVariable.LIST.getVariable(), errorCodeList);//类名 + error.binding(TemplateVariable.LIST.getVariable(), errorCodeList); String errorHtml = MarkDownUtil.toHtml(error.render()); Template errorCodeDoc = BeetlTemplateUtil.getByName(HTML_API_DOC_TPL); errorCodeDoc.binding(TemplateVariable.VERSION.getVariable(), now); @@ -120,7 +127,6 @@ public class HtmlApiDocBuilder { errorCodeDoc.binding(TemplateVariable.HTML.getVariable(), errorHtml); errorCodeDoc.binding(TemplateVariable.CREATE_TIME.getVariable(), DateTimeUtil.long2Str(now, DateTimeUtil.DATE_FORMAT_SECOND)); FileUtil.nioWriteFile(errorCodeDoc.render(), outPath + FILE_SEPARATOR + "error_code.html"); - } } } diff --git a/src/main/java/com/power/doc/builder/SourceBuilder.java b/src/main/java/com/power/doc/builder/SourceBuilder.java index 0148641..069ea5a 100644 --- a/src/main/java/com/power/doc/builder/SourceBuilder.java +++ b/src/main/java/com/power/doc/builder/SourceBuilder.java @@ -1,6 +1,9 @@ package com.power.doc.builder; -import com.power.common.util.*; +import com.power.common.util.CollectionUtil; +import com.power.common.util.JsonFormatUtil; +import com.power.common.util.StringUtil; +import com.power.common.util.UrlUtil; import com.power.doc.constants.DocAnnotationConstants; import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.DocTags; @@ -10,6 +13,7 @@ import com.power.doc.utils.DocUtil; import com.power.doc.utils.PathUtil; import com.thoughtworks.qdox.JavaProjectBuilder; import com.thoughtworks.qdox.model.*; +import org.apache.commons.codec.digest.DigestUtils; import java.io.File; import java.util.*; @@ -36,16 +40,18 @@ public class SourceBuilder { private static final String MAP_CLASS = "java.util.Map"; + private static final String NO_COMMENTS_FOUND = "No comments found."; - public Map javaFilesMap = new HashMap<>(); - public Map fieldMap = new HashMap<>(); + + private Map javaFilesMap = new HashMap<>(); + private Map fieldMap = new HashMap<>(); private JavaProjectBuilder builder; private Collection javaClasses; - private boolean isStrict;//严格模式 + private boolean isStrict;//Strict mode private String packageMatch; private List headers; private String appUrl; - private ApiAesInfo aesInfo; + private boolean isUseMD5; /** * if isStrict value is true,it while check all method @@ -73,10 +79,10 @@ public class SourceBuilder { this.appUrl = config.getServerUrl(); } - aesInfo = config.getAesInfo(); + isUseMD5 = config.isMd5EncryptedHtmlName(); this.packageMatch = config.getPackageFilters(); this.isStrict = config.isStrict(); - loadJavaFiles(config.getSourcePaths()); + loadJavaFiles(config.getSourceCodePaths()); this.headers = config.getRequestHeaders(); if (CollectionUtil.isNotEmpty(config.getCustomResponseFields())) { for (CustomRespField field : config.getCustomResponseFields()) { @@ -86,71 +92,9 @@ public class SourceBuilder { } /** - * 加载项目的源代码 - * - * @param paths list of SourcePath + * Get api data + * @return List of api data */ - private void loadJavaFiles(List paths) { - JavaProjectBuilder builder = new JavaProjectBuilder(); - if (CollectionUtil.isEmpty(paths)) { - builder.addSourceTree(new File("src/main/java")); - } else { - for (SourcePath path : paths) { - if (null == path) { - continue; - } - String strPath = path.getPath(); - if (StringUtil.isNotEmpty(strPath)) { - strPath = strPath.replace("\\", "/"); - builder.addSourceTree(new File(strPath)); - } - } - } - this.builder = builder; - this.javaClasses = builder.getClasses(); - for (JavaClass cls : javaClasses) { - javaFilesMap.put(cls.getFullyQualifiedName(), cls); - } - } - - /** - * 检测controller上的注解 - * - * @param cls - * @return - */ - private boolean checkController(JavaClass cls) { - List classAnnotations = cls.getAnnotations(); - for (JavaAnnotation annotation : classAnnotations) { - String annotationName = annotation.getType().getName(); - if (DocAnnotationConstants.SHORT_CONTROLLER.equals(annotationName) - || DocAnnotationConstants.SHORT_REST_CONTROLLER.equals(annotationName) - || DocGlobalConstants.REST_CONTROLLER_FULLY.equals(annotationName) - || DocGlobalConstants.CONTROLLER_FULLY.equals(annotationName) - ) { - return true; - } - } - return false; - } - - /** - * 检查是否是rest controller - * - * @param cls The JavaClass object - * @return boolean - */ - private boolean isRestController(JavaClass cls) { - List classAnnotations = cls.getAnnotations(); - for (JavaAnnotation annotation : classAnnotations) { - String annotationName = annotation.getType().getName(); - if (DocAnnotationConstants.SHORT_REST_CONTROLLER.equals(annotationName)) { - return true; - } - } - return false; - } - public List getControllerApiData() { List apiDocList = new ArrayList<>(); int order = 0; @@ -189,9 +133,9 @@ public class SourceBuilder { /** - * 包括包名 + * Get single controller api data by controller fully name. * - * @param controller controller的名称 + * @param controller controller fully name * @return ApiDoc */ public ApiDoc getSingleControllerApiData(String controller) { @@ -211,7 +155,7 @@ public class SourceBuilder { } } - public List buildControllerMethod(final JavaClass cls) { + private List buildControllerMethod(final JavaClass cls) { List classAnnotations = cls.getAnnotations(); String baseUrl = ""; for (JavaAnnotation annotation : classAnnotations) { @@ -293,6 +237,33 @@ public class SourceBuilder { } + /** + * load source code + * + * @param paths list of SourcePath + */ + private void loadJavaFiles(List paths) { + JavaProjectBuilder builder = new JavaProjectBuilder(); + if (CollectionUtil.isEmpty(paths)) { + builder.addSourceTree(new File("src/main/java")); + } else { + for (SourceCodePath path : paths) { + if (null == path) { + continue; + } + String strPath = path.getPath(); + if (StringUtil.isNotEmpty(strPath)) { + strPath = strPath.replace("\\", "/"); + builder.addSourceTree(new File(strPath)); + } + } + } + this.builder = builder; + this.javaClasses = builder.getClasses(); + for (JavaClass cls : javaClasses) { + javaFilesMap.put(cls.getFullyQualifiedName(), cls); + } + } /** * create request headers * @@ -359,6 +330,8 @@ public class SourceBuilder { } /** + * build request params list or response fields list + * * @param className class name * @param pre pre * @param i counter @@ -490,9 +463,9 @@ public class SourceBuilder { } } else { if (StringUtil.isEmpty(isRequired)) { - params0.append("No comments found.").append("|").append(since).append("\n"); + params0.append(NO_COMMENTS_FOUND).append("|").append(since).append("\n"); } else { - params0.append("No comments found.").append("|").append(strRequired) + params0.append(NO_COMMENTS_FOUND).append("|").append(strRequired) .append("|").append(since).append("\n"); } } @@ -509,7 +482,7 @@ public class SourceBuilder { } } else { if (StringUtil.isEmpty(isRequired)) { - params0.append("No comments found.").append("|").append(since).append("\n"); + params0.append(NO_COMMENTS_FOUND).append("|").append(since).append("\n"); } else { params0.append("No comments found|").append(strRequired) .append("|").append(since).append("\n"); @@ -615,20 +588,20 @@ public class SourceBuilder { StringBuilder comments = new StringBuilder(); comments.append("no param name|") .append(typeName).append("|") - .append("The interface directly returns the ") + .append("The api directly returns the ") .append(typeName).append(" type value.").append("|-\n"); return comments.toString(); } /** - * 构建返回的json + * build return json * * @param method The JavaMethod object * @return String */ private String buildReturnJson(JavaMethod method, Map responseFieldMap) { if ("void".equals(method.getReturnType().getFullyQualifiedName())) { - return "this api return nothing."; + return "This api return nothing."; } ApiReturn apiReturn = DocClassUtil.processReturnType(method.getReturnType().getGenericCanonicalName()); String returnType = apiReturn.getGenericCanonicalName(); @@ -646,9 +619,9 @@ public class SourceBuilder { private String buildJson(String typeName, String genericCanonicalName, Map responseFieldMap, boolean isResp) { if (DocClassUtil.isMvcIgnoreParams(typeName)) { if (DocGlobalConstants.MODE_AND_VIEW_FULLY.equals(typeName)) { - return "forward or redirect to a page view."; + return "Forward or redirect to a page view."; } else { - return "error restful return."; + return "Error restful return."; } } if (DocClassUtil.isPrimitive(typeName)) { @@ -955,13 +928,13 @@ public class SourceBuilder { String pName; String pValue; int idx = value.indexOf("\n"); - //如果存在换行 + //existed \n if (idx > -1) { pName = value.substring(0, idx); pValue = value.substring(idx + 1); } else { pName = (value.indexOf(" ") > -1) ? value.substring(0, value.indexOf(" ")) : value; - pValue = value.indexOf(" ") > -1 ? value.substring(value.indexOf(' ') + 1) : "No comments found."; + pValue = value.indexOf(" ") > -1 ? value.substring(value.indexOf(' ') + 1) : NO_COMMENTS_FOUND; } paramTagMap.put(pName, pValue); } @@ -985,7 +958,7 @@ public class SourceBuilder { } String comment = paramTagMap.get(paramName); if (StringUtil.isEmpty(comment)) { - comment = "No comments found."; + comment = NO_COMMENTS_FOUND; } List annotations = parameter.getAnnotations(); if (annotations.size() == 0) { @@ -1111,15 +1084,52 @@ public class SourceBuilder { return fieldList; } + /** + * check controller + * + * @param cls + * @return + */ + private boolean checkController(JavaClass cls) { + List classAnnotations = cls.getAnnotations(); + for (JavaAnnotation annotation : classAnnotations) { + String annotationName = annotation.getType().getName(); + if (DocAnnotationConstants.SHORT_CONTROLLER.equals(annotationName) + || DocAnnotationConstants.SHORT_REST_CONTROLLER.equals(annotationName) + || DocGlobalConstants.REST_CONTROLLER_FULLY.equals(annotationName) + || DocGlobalConstants.CONTROLLER_FULLY.equals(annotationName) + ) { + return true; + } + } + return false; + } + + /** + * is rest controller + * + * @param cls The JavaClass object + * @return boolean + */ + private boolean isRestController(JavaClass cls) { + List classAnnotations = cls.getAnnotations(); + for (JavaAnnotation annotation : classAnnotations) { + String annotationName = annotation.getType().getName(); + if (DocAnnotationConstants.SHORT_REST_CONTROLLER.equals(annotationName)) { + return true; + } + } + return false; + } + /** * handle controller name * * @param apiDoc ApiDoc */ private void handControllerAlias(ApiDoc apiDoc) { - if (null != aesInfo && StringUtil.isNotEmpty(aesInfo.getKey()) - && StringUtil.isNotEmpty(aesInfo.getVector())) { - String name = AESUtil.encodeByCBC(apiDoc.getName(), aesInfo.getKey(), aesInfo.getVector()); + if (isUseMD5) { + String name = DigestUtils.md5Hex(apiDoc.getName()); int length = name.length(); if (name.length() < 32) { apiDoc.setAlias(name); diff --git a/src/main/java/com/power/doc/constants/DocLanguage.java b/src/main/java/com/power/doc/constants/DocLanguage.java index 82a9511..c8aafd6 100644 --- a/src/main/java/com/power/doc/constants/DocLanguage.java +++ b/src/main/java/com/power/doc/constants/DocLanguage.java @@ -1,7 +1,8 @@ package com.power.doc.constants; /** - * 语言支持 + * + * language support * @author yu 2019/9/21. */ public enum DocLanguage { diff --git a/src/main/java/com/power/doc/model/ApiAesInfo.java b/src/main/java/com/power/doc/model/ApiAesInfo.java deleted file mode 100644 index 9e85533..0000000 --- a/src/main/java/com/power/doc/model/ApiAesInfo.java +++ /dev/null @@ -1,41 +0,0 @@ -package com.power.doc.model; - -/** - * aes加密信息 - * @since 1.7+ - * @author yu 2019/9/21. - */ -public class ApiAesInfo { - - /** - * aes加密key - */ - private String key; - - /** - * 加密初始向量 - */ - private String vector; - - public static ApiAesInfo create() { - return new ApiAesInfo(); - } - - public String getKey() { - return key; - } - - public ApiAesInfo setKey(String key) { - this.key = key; - return this; - } - - public String getVector() { - return vector; - } - - public ApiAesInfo setVector(String vector) { - this.vector = vector; - return this; - } -} diff --git a/src/main/java/com/power/doc/model/ApiConfig.java b/src/main/java/com/power/doc/model/ApiConfig.java index cc62361..eecea3f 100644 --- a/src/main/java/com/power/doc/model/ApiConfig.java +++ b/src/main/java/com/power/doc/model/ApiConfig.java @@ -37,7 +37,7 @@ public class ApiConfig { /** * source path */ - private List sourcePaths; + private List sourceCodePaths; /** * 请求头 @@ -69,9 +69,8 @@ public class ApiConfig { /** * @since 1.7+ - * aes加密信息 */ - private ApiAesInfo aesInfo; + private boolean md5EncryptedHtmlName; /** * 语言 @@ -129,12 +128,12 @@ public class ApiConfig { this.errorCodes = errorCodes; } - public List getSourcePaths() { - return sourcePaths; + public List getSourceCodePaths() { + return sourceCodePaths; } - public void setSourcePaths(SourcePath... sourcePaths) { - this.sourcePaths = CollectionUtil.asList(sourcePaths); + public void setSourcePaths(SourceCodePath... sourcePaths) { + this.sourceCodePaths = CollectionUtil.asList(sourcePaths); } public boolean isAllInOne() { @@ -161,12 +160,12 @@ public class ApiConfig { this.revisionLogs = CollectionUtil.asList(revisionLogs); } - public ApiAesInfo getAesInfo() { - return aesInfo; + public boolean isMd5EncryptedHtmlName() { + return md5EncryptedHtmlName; } - public void setAesInfo(ApiAesInfo aesInfo) { - this.aesInfo = aesInfo; + public void setMd5EncryptedHtmlName(boolean md5EncryptedHtmlName) { + this.md5EncryptedHtmlName = md5EncryptedHtmlName; } public DocLanguage getLanguage() { @@ -176,4 +175,6 @@ public class ApiConfig { public void setLanguage(DocLanguage language) { this.language = language; } + + } diff --git a/src/main/java/com/power/doc/model/ApiErrorCode.java b/src/main/java/com/power/doc/model/ApiErrorCode.java index d23de3e..bda88a2 100644 --- a/src/main/java/com/power/doc/model/ApiErrorCode.java +++ b/src/main/java/com/power/doc/model/ApiErrorCode.java @@ -2,19 +2,19 @@ package com.power.doc.model; /** * Description: - * restful api错误码 + * restful api error code * * @author yu 2018/06/25. */ public class ApiErrorCode { /** - * 错误码 + * error code */ private String value; /** - * 错误描述 + * error description */ private String desc; diff --git a/src/main/java/com/power/doc/model/ApiMethodDoc.java b/src/main/java/com/power/doc/model/ApiMethodDoc.java index 6be06cf..d19bed8 100644 --- a/src/main/java/com/power/doc/model/ApiMethodDoc.java +++ b/src/main/java/com/power/doc/model/ApiMethodDoc.java @@ -3,31 +3,61 @@ package com.power.doc.model; import java.io.Serializable; /** - * api文档 + * java api method info model. */ public class ApiMethodDoc implements Serializable { + + private static final long serialVersionUID = 7211922919532562867L; /** * @since 1.7+ + * method order */ private int order; + /** + * method description + */ private String desc; + /** + * controller method url + */ private String url; + /** + * http request type + */ private String type; + /** + * http readers + */ private String headers; + /** + * http contentType + */ private String contentType = "application/x-www-form-urlencoded"; + /** + * http request params + */ private String requestParams; + /** + * http request usage + */ private String requestUsage; + /** + * http response usage + */ private String responseUsage; + /** + * http response params + */ private String responseParams; diff --git a/src/main/java/com/power/doc/model/ApiReqHeader.java b/src/main/java/com/power/doc/model/ApiReqHeader.java index fe1c0aa..f42b798 100644 --- a/src/main/java/com/power/doc/model/ApiReqHeader.java +++ b/src/main/java/com/power/doc/model/ApiReqHeader.java @@ -2,35 +2,35 @@ package com.power.doc.model; /** * Description: - * 请求头 + * http request header info model * * @author yu 2018/06/18. */ public class ApiReqHeader { /** - * 请求头的名称 + * Request header name */ private String name; /** - * 请求头类型 + * Request header type */ private String type; /** - * 请求头描述 + * Request header description */ private String desc; /** * @since 1.7.0 - * 请求有是否必须 + * required flag */ private boolean required; /** * @since 1.7.0 - * 起始版本 + * Starting version number */ private String since = "-"; diff --git a/src/main/java/com/power/doc/model/CustomRespField.java b/src/main/java/com/power/doc/model/CustomRespField.java index 993122a..a1ca8a9 100644 --- a/src/main/java/com/power/doc/model/CustomRespField.java +++ b/src/main/java/com/power/doc/model/CustomRespField.java @@ -2,29 +2,29 @@ package com.power.doc.model; /** * Description: - * Api 自动义字段修正 - * + * This can be used to customize the comments for setting java fields. + * You can reference README.md * @author yu 2018/06/18. */ public class CustomRespField { /** - * 字段名 + * field name */ private String name; /** - * 字段描述 + * field description */ private String desc; /** - * 字段隶属类 + * owner class */ private String ownerClassName; /** - * 默认值 + * default value */ private Object value; diff --git a/src/main/java/com/power/doc/model/SourcePath.java b/src/main/java/com/power/doc/model/SourceCodePath.java similarity index 61% rename from src/main/java/com/power/doc/model/SourcePath.java rename to src/main/java/com/power/doc/model/SourceCodePath.java index fa697b2..1d5d9e1 100644 --- a/src/main/java/com/power/doc/model/SourcePath.java +++ b/src/main/java/com/power/doc/model/SourceCodePath.java @@ -1,12 +1,13 @@ package com.power.doc.model; /** + * Source code path * @author yu 2018/7/14. */ -public class SourcePath { +public class SourceCodePath { /** - * Source path + * Source code path */ private String path; @@ -15,15 +16,15 @@ public class SourcePath { */ private String desc; - public static SourcePath path() { - return new SourcePath(); + public static SourceCodePath path() { + return new SourceCodePath(); } public String getPath() { return path; } - public SourcePath setPath(String path) { + public SourceCodePath setPath(String path) { this.path = path; return this; } @@ -32,7 +33,7 @@ public class SourcePath { return desc; } - public SourcePath setDesc(String desc) { + public SourceCodePath setDesc(String desc) { this.desc = desc; return this; } diff --git a/src/main/java/com/power/doc/utils/BeetlTemplateUtil.java b/src/main/java/com/power/doc/utils/BeetlTemplateUtil.java index 6f9c1fe..40aa992 100644 --- a/src/main/java/com/power/doc/utils/BeetlTemplateUtil.java +++ b/src/main/java/com/power/doc/utils/BeetlTemplateUtil.java @@ -12,11 +12,18 @@ import java.util.HashMap; import java.util.Map; /** - * 获取模板 + * Beetl template handle util * * @author sunyu on 2016/12/6. */ public class BeetlTemplateUtil { + + + /** + * Get Beetl template by file name + * @param templateName + * @return Beetl Template Object + */ public static Template getByName(String templateName) { try { ClasspathResourceLoader resourceLoader = new ClasspathResourceLoader("/template/"); @@ -24,11 +31,13 @@ public class BeetlTemplateUtil { GroupTemplate gt = new GroupTemplate(resourceLoader, cfg); return gt.getTemplate(templateName); } catch (IOException e) { - throw new RuntimeException("获取模板异常"); + throw new RuntimeException("Can't get Beetl template."); } } /** + * Batch bind binding value to Beetl templates and return all file rendered, + * Map key is file name,value is file content * @param path path * @param params params * @return map @@ -61,7 +70,7 @@ public class BeetlTemplateUtil { GroupTemplate gt = new GroupTemplate(resourceLoader, cfg); return gt; } catch (IOException e) { - throw new RuntimeException("获取模板异常"); + throw new RuntimeException("Can't get Beetl template."); } } } diff --git a/src/main/java/com/power/doc/utils/DocClassUtil.java b/src/main/java/com/power/doc/utils/DocClassUtil.java index e6514ce..92a1df8 100644 --- a/src/main/java/com/power/doc/utils/DocClassUtil.java +++ b/src/main/java/com/power/doc/utils/DocClassUtil.java @@ -8,7 +8,7 @@ import java.util.List; /** * Description: - * class的工具 + * Doc class handle util * * @author yu 2018//14. */ diff --git a/src/main/java/com/power/doc/utils/DocUtil.java b/src/main/java/com/power/doc/utils/DocUtil.java index a366a9a..cb9551d 100644 --- a/src/main/java/com/power/doc/utils/DocUtil.java +++ b/src/main/java/com/power/doc/utils/DocUtil.java @@ -79,13 +79,13 @@ public class DocUtil { } /** - * 随机生成json值 + * Generate a random value based on java type name. * - * @param type0 type name - * @return string + * @param typeName field type name + * @return random value */ - public static String jsonValueByType(String type0) { - String type = type0.contains(".") ? type0.substring(type0.lastIndexOf(".") + 1, type0.length()) : type0; + public static String jsonValueByType(String typeName) { + String type = typeName.contains(".") ? typeName.substring(typeName.lastIndexOf(".") + 1, typeName.length()) : typeName; String value = RandomUtil.randomValueByType(type); if ("Integer".equals(type) || "int".equals(type) || "Long".equals(type) || "long".equals(type) || "Double".equals(type) || "double".equals(type) || "Float".equals(type) || "float".equals(type) || @@ -100,14 +100,14 @@ public class DocUtil { } /** - * 根据字段字段名和type生成字段值 + * Generate random field values based on field field names and type. * - * @param type0 类型 - * @param filedName 字段名称 - * @return string + * @param typeName field type name + * @param filedName field name + * @return random value */ - public static String getValByTypeAndFieldName(String type0, String filedName) { - String type = type0.contains("java.lang") ? type0.substring(type0.lastIndexOf(".") + 1, type0.length()) : type0; + public static String getValByTypeAndFieldName(String typeName, String filedName) { + String type = typeName.contains("java.lang") ? typeName.substring(typeName.lastIndexOf(".") + 1, typeName.length()) : typeName; String key = filedName.toLowerCase() + "-" + type.toLowerCase(); String value = null; for (Map.Entry entry : fieldValue.entrySet()) { @@ -117,7 +117,7 @@ public class DocUtil { } } if (null == value) { - return jsonValueByType(type0); + return jsonValueByType(typeName); } else { if ("string".equals(type.toLowerCase())) { StringBuilder builder = new StringBuilder(); diff --git a/src/main/java/com/power/doc/utils/MarkDownUtil.java b/src/main/java/com/power/doc/utils/MarkDownUtil.java index 576227d..d5d1391 100644 --- a/src/main/java/com/power/doc/utils/MarkDownUtil.java +++ b/src/main/java/com/power/doc/utils/MarkDownUtil.java @@ -16,10 +16,10 @@ import java.util.Arrays; public class MarkDownUtil { /** - * markdown to html + * Convert markdown to html. * * @param content markdown contents - * @return parse html contents + * @return html contents */ public static String toHtml(String content) { MutableDataSet options = new MutableDataSet(); diff --git a/src/main/java/com/power/doc/utils/PathUtil.java b/src/main/java/com/power/doc/utils/PathUtil.java index 0e4540c..ca2202b 100644 --- a/src/main/java/com/power/doc/utils/PathUtil.java +++ b/src/main/java/com/power/doc/utils/PathUtil.java @@ -8,11 +8,11 @@ import java.io.File; public class PathUtil { /** - * 获取java类名 + * Get the java class name * * @param parentDir parent dir - * @param className 类名 - * @return string + * @param className class name + * @return java file name */ public static String javaFilePath(String parentDir, String className) { if (StringUtil.isEmpty(parentDir)) { @@ -26,9 +26,9 @@ public class PathUtil { } /** - * process http url + * Replace '//' with '/' in the url. * @param url url - * @return String + * @return processed url */ public static String processHttpUrl(String url) { int index = url.indexOf("//"); diff --git a/src/main/resources/template/AllInOne.btl b/src/main/resources/template/AllInOne.btl index 9b070aa..61f8933 100644 --- a/src/main/resources/template/AllInOne.btl +++ b/src/main/resources/template/AllInOne.btl @@ -1,5 +1,5 @@ <%if(isNotEmpty(revisionLogList)){%> -版本 | 时间 | 状态 | 作者 | 备注 +Version | Update Time | Status | Author | Description ------|--------|-----|------| ------- <% for(revisionLog in revisionLogList){