From 66b30b8abb014a6c9df04ac80c4581bfa5c7dfd1 Mon Sep 17 00:00:00 2001 From: oppofind <836575280@qq.com> Date: Fri, 27 Sep 2019 00:09:37 +0800 Subject: [PATCH] and adoc support --- .../com/power/doc/builder/AdocDocBuilder.java | 35 ++++++ .../com/power/doc/builder/ApiDocBuilder.java | 106 ++---------------- .../power/doc/builder/BuilderTemplate.java | 92 +++++++++++++++ .../power/doc/builder/HtmlApiDocBuilder.java | 4 +- .../doc/constants/DocGlobalConstants.java | 14 ++- 5 files changed, 150 insertions(+), 101 deletions(-) create mode 100644 src/main/java/com/power/doc/builder/AdocDocBuilder.java create mode 100644 src/main/java/com/power/doc/builder/BuilderTemplate.java diff --git a/src/main/java/com/power/doc/builder/AdocDocBuilder.java b/src/main/java/com/power/doc/builder/AdocDocBuilder.java new file mode 100644 index 0000000..0d8ce6e --- /dev/null +++ b/src/main/java/com/power/doc/builder/AdocDocBuilder.java @@ -0,0 +1,35 @@ +package com.power.doc.builder; + +import com.power.doc.model.ApiConfig; +import com.power.doc.model.ApiDoc; + +import java.util.List; + +import static com.power.doc.constants.DocGlobalConstants.*; + +/** + * Use to create Asciidoc + * @author yu 2019/9/26. + */ +public class AdocDocBuilder { + + private static final String API_EXTENSION = "Api.adoc"; + + private static final String INDEX_DOC = "index.adoc"; + + /** build adoc + * @param config ApiConfig + */ + public static void builderControllersApi(ApiConfig config) { + BuilderTemplate builderTemplate = new BuilderTemplate(); + builderTemplate.checkAndInit(config); + SourceBuilder sourceBuilder = new SourceBuilder(config); + List apiDocList = sourceBuilder.getControllerApiData(); + if (config.isAllInOne()) { + builderTemplate.buildAllInOne(apiDocList,config,ALL_IN_ONE_ADOC_TPL,INDEX_DOC); + } else { + builderTemplate.buildApiDoc(apiDocList,config,API_DOC_ADOC_TPL,API_EXTENSION); + builderTemplate.buildErrorCodeDoc(config.getErrorCodes(),config,ERROR_CODE_LIST_ADOC_TPL,ERROR_CODE_LIST_ADOC); + } + } +} diff --git a/src/main/java/com/power/doc/builder/ApiDocBuilder.java b/src/main/java/com/power/doc/builder/ApiDocBuilder.java index cd6e7f8..86575e3 100644 --- a/src/main/java/com/power/doc/builder/ApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/ApiDocBuilder.java @@ -1,17 +1,8 @@ package com.power.doc.builder; -import com.power.common.util.CollectionUtil; import com.power.common.util.DateTimeUtil; -import com.power.common.util.FileUtil; -import com.power.common.util.StringUtil; -import com.power.doc.constants.DocGlobalConstants; -import com.power.doc.constants.DocLanguage; -import com.power.doc.constants.TemplateVariable; import com.power.doc.model.ApiConfig; import com.power.doc.model.ApiDoc; -import com.power.doc.model.ApiErrorCode; -import com.power.doc.utils.BeetlTemplateUtil; -import org.beetl.core.Template; import java.util.List; @@ -24,105 +15,26 @@ import static com.power.doc.constants.DocGlobalConstants.*; */ public class ApiDocBuilder { - /** - * 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); - List apiDocList = sourceBuilder.getControllerApiData(); - buildApiDoc(apiDocList, outPath); - } + private static final String API_EXTENSION = "Api.md"; + + private static final String DATE_FORMAT = "yyyyMMddHHmm"; /** * @param config ApiConfig */ public static void builderControllersApi(ApiConfig config) { - if (null == config) { - throw new NullPointerException("ApiConfig can't be null"); - } - if (StringUtil.isEmpty(config.getOutPath())) { - throw new RuntimeException("doc output path can't be null or empty"); - } - if (null != config.getLanguage()) { - System.setProperty(DocGlobalConstants.DOC_LANGUAGE, config.getLanguage().getCode()); - } else { - //default is chinese - System.setProperty(DocGlobalConstants.DOC_LANGUAGE, DocLanguage.CHINESE.getCode()); - } + BuilderTemplate builderTemplate = new BuilderTemplate(); + builderTemplate.checkAndInit(config); SourceBuilder sourceBuilder = new SourceBuilder(config); List apiDocList = sourceBuilder.getControllerApiData(); if (config.isAllInOne()) { - buildAllInOne(apiDocList, config); + String version = DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT); + builderTemplate.buildAllInOne(apiDocList,config,ALL_IN_ONE_MD_TPL,"AllInOne-V" + version + ".md"); } else { - buildApiDoc(apiDocList, config.getOutPath()); - buildErrorCodeDoc(config.getErrorCodes(), config.getOutPath()); + builderTemplate.buildApiDoc(apiDocList,config,API_DOC_MD_TPL,API_EXTENSION); + builderTemplate.buildErrorCodeDoc(config.getErrorCodes(),config,ERROR_CODE_LIST_MD_TPL,ERROR_CODE_LIST_MD); } } - /** - * Generate a single controller api document - * - * @param outPath output path - * @param controllerName controller name - */ - public static void buildSingleControllerApi(String outPath, String controllerName) { - FileUtil.mkdirs(outPath); - SourceBuilder sourceBuilder = new SourceBuilder(true); - ApiDoc doc = sourceBuilder.getSingleControllerApiData(controllerName); - 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()); - FileUtil.writeFileNotAppend(mapper.render(), outPath + FILE_SEPARATOR + doc.getName() + "Api.md"); - } - /** - * Generate api documentation for all controllers. - * - * @param apiDocList list of api doc - * @param outPath output path - */ - private static void buildApiDoc(List apiDocList, String outPath) { - FileUtil.mkdirs(outPath); - for (ApiDoc doc : apiDocList) { - 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()); - FileUtil.nioWriteFile(mapper.render(), outPath + FILE_SEPARATOR + doc.getName() + "Api.md"); - } - } - - /** - * Merge all api doc into one document - * - * @param apiDocList - */ - private static void buildAllInOne(List apiDocList, ApiConfig config) { - String outPath = config.getOutPath(); - FileUtil.mkdirs(outPath); - Template tpl = BeetlTemplateUtil.getByName("AllInOne.btl"); - tpl.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); - tpl.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), config.getErrorCodes()); - tpl.binding(TemplateVariable.VERSION_LIST.getVariable(), config.getRevisionLogs()); - String version = DateTimeUtil.long2Str(System.currentTimeMillis(), "yyyyMMddHHmm"); - FileUtil.nioWriteFile(tpl.render(), outPath + FILE_SEPARATOR + "AllInOne-V" + version + ".md"); - } - - /** - * build error_code html - * - * @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); - FileUtil.nioWriteFile(mapper.render(), outPath + FILE_SEPARATOR + ERROR_CODE_LIST_MD); - } - } } diff --git a/src/main/java/com/power/doc/builder/BuilderTemplate.java b/src/main/java/com/power/doc/builder/BuilderTemplate.java new file mode 100644 index 0000000..eefbb2b --- /dev/null +++ b/src/main/java/com/power/doc/builder/BuilderTemplate.java @@ -0,0 +1,92 @@ +package com.power.doc.builder; + +import com.power.common.util.CollectionUtil; +import com.power.common.util.FileUtil; +import com.power.common.util.StringUtil; +import com.power.doc.constants.DocGlobalConstants; +import com.power.doc.constants.DocLanguage; +import com.power.doc.constants.TemplateVariable; +import com.power.doc.model.ApiConfig; +import com.power.doc.model.ApiDoc; +import com.power.doc.model.ApiErrorCode; +import com.power.doc.utils.BeetlTemplateUtil; +import org.beetl.core.Template; + +import java.util.List; + +import static com.power.doc.constants.DocGlobalConstants.FILE_SEPARATOR; + +/** + * @author yu 2019/9/26. + */ +public class BuilderTemplate { + + + /** + * check condition and init + * + * @param config + */ + public void checkAndInit(ApiConfig config) { + if (null == config) { + throw new NullPointerException("ApiConfig can't be null"); + } + if (StringUtil.isEmpty(config.getOutPath())) { + throw new RuntimeException("doc output path can't be null or empty"); + } + if (null != config.getLanguage()) { + System.setProperty(DocGlobalConstants.DOC_LANGUAGE, config.getLanguage().getCode()); + } else { + //default is chinese + System.setProperty(DocGlobalConstants.DOC_LANGUAGE, DocLanguage.CHINESE.getCode()); + } + } + + /** + * Generate api documentation for all controllers. + * + * @param apiDocList list of api doc + * @param config api config + * @param template template + * @param fileExtension file extension + */ + public void buildApiDoc(List apiDocList, ApiConfig config, String template, String fileExtension) { + FileUtil.mkdirs(config.getOutPath()); + for (ApiDoc doc : apiDocList) { + Template mapper = BeetlTemplateUtil.getByName(template); + mapper.binding(TemplateVariable.DESC.getVariable(), doc.getDesc()); + mapper.binding(TemplateVariable.NAME.getVariable(), doc.getName()); + mapper.binding(TemplateVariable.LIST.getVariable(), doc.getList()); + FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + doc.getName() + fileExtension); + } + } + + /** + * Merge all api doc into one document + * + * @param apiDocList + */ + public void buildAllInOne(List apiDocList, ApiConfig config, String template, String outPutFileName) { + String outPath = config.getOutPath(); + FileUtil.mkdirs(outPath); + Template tpl = BeetlTemplateUtil.getByName(template); + tpl.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); + tpl.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), config.getErrorCodes()); + tpl.binding(TemplateVariable.VERSION_LIST.getVariable(), config.getRevisionLogs()); + FileUtil.nioWriteFile(tpl.render(), outPath + FILE_SEPARATOR + outPutFileName); + } + + /** + * build error_code html + * + * @param errorCodeList list of error code + * @param outPath + */ + public void buildErrorCodeDoc(List errorCodeList, ApiConfig config, String template, String outPutFileName) { + if (CollectionUtil.isNotEmpty(errorCodeList)) { + Template mapper = BeetlTemplateUtil.getByName(template); + mapper.binding(TemplateVariable.LIST.getVariable(), errorCodeList); + FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName); + } + } +} diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index fe4c998..6607d49 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -95,7 +95,7 @@ public class HtmlApiDocBuilder { Template htmlApiDoc; String strTime = DateTimeUtil.long2Str(now, DateTimeUtil.DATE_FORMAT_SECOND); for (ApiDoc doc : apiDocList) { - Template apiTemplate = BeetlTemplateUtil.getByName(API_DOC_TPL); + Template apiTemplate = BeetlTemplateUtil.getByName(API_DOC_MD_TPL); apiTemplate.binding(TemplateVariable.DESC.getVariable(), doc.getDesc()); apiTemplate.binding(TemplateVariable.NAME.getVariable(), doc.getName()); apiTemplate.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名 @@ -118,7 +118,7 @@ public class HtmlApiDocBuilder { */ private static void buildErrorCodeDoc(List errorCodeList, String outPath) { if (CollectionUtil.isNotEmpty(errorCodeList)) { - Template error = BeetlTemplateUtil.getByName(ERROR_CODE_LIST_TPL); + Template error = BeetlTemplateUtil.getByName(ERROR_CODE_LIST_MD_TPL); error.binding(TemplateVariable.LIST.getVariable(), errorCodeList); String errorHtml = MarkDownUtil.toHtml(error.render()); Template errorCodeDoc = BeetlTemplateUtil.getByName(HTML_API_DOC_TPL); diff --git a/src/main/java/com/power/doc/constants/DocGlobalConstants.java b/src/main/java/com/power/doc/constants/DocGlobalConstants.java index ba9de02..f800828 100644 --- a/src/main/java/com/power/doc/constants/DocGlobalConstants.java +++ b/src/main/java/com/power/doc/constants/DocGlobalConstants.java @@ -13,14 +13,24 @@ public class DocGlobalConstants { public static final String DOC_LANGUAGE = "smart-doc_language"; - public static final String API_DOC_TPL = "ApiDoc.btl"; + public static final String API_DOC_MD_TPL = "ApiDoc.btl"; + + public static final String API_DOC_ADOC_TPL = "ApiDoc.adoc"; + + public static final String ALL_IN_ONE_MD_TPL = "AllInOne.btl"; + + public static final String ALL_IN_ONE_ADOC_TPL = "AllInOne.adoc"; public static final String HTML_API_DOC_TPL = "HtmlApiDoc.btl"; - public static final String ERROR_CODE_LIST_TPL = "ErrorCodeList.btl"; + public static final String ERROR_CODE_LIST_MD_TPL = "ErrorCodeList.btl"; + + public static final String ERROR_CODE_LIST_ADOC_TPL = "ErrorCodeList.btl"; public static final String ERROR_CODE_LIST_MD = "ErrorCodeList.md"; + public static final String ERROR_CODE_LIST_ADOC = "ErrorCodeList.md"; + public static final String INDEX_TPL = "Index.btl"; public static final String INDEX_CSS_TPL = "index.css";