diff --git a/src/main/java/com/power/doc/builder/DocBuilderTemplate.java b/src/main/java/com/power/doc/builder/DocBuilderTemplate.java index 18945d7..e730a45 100644 --- a/src/main/java/com/power/doc/builder/DocBuilderTemplate.java +++ b/src/main/java/com/power/doc/builder/DocBuilderTemplate.java @@ -96,20 +96,36 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate { * @param template template * @param outPutFileName output file */ - public void buildAllInOne(List apiDocList, ApiConfig config, JavaProjectBuilder javaProjectBuilder, String template, String outPutFileName) { + public void buildAllInOne(List apiDocList, ApiConfig config, JavaProjectBuilder javaProjectBuilder, + String template, String outPutFileName) { + buildDoc(apiDocList, config, javaProjectBuilder, template, outPutFileName, null); + } + + /** + * Merge all api doc into one document + * + * @param apiDocList list data of Api doc + * @param config api config + * @param javaProjectBuilder JavaProjectBuilder + * @param template template + * @param outPutFileName output file + * @param apiDoc apiDoc + */ + public void buildDoc(List apiDocList, ApiConfig config, JavaProjectBuilder javaProjectBuilder, + String template, String outPutFileName, ApiDoc apiDoc) { String outPath = config.getOutPath(); String strTime = DateTimeUtil.long2Str(now, DateTimeUtil.DATE_FORMAT_SECOND); FileUtil.mkdirs(outPath); List errorCodeList = errorCodeDictToList(config); - Template tpl = BeetlTemplateUtil.getByName(template); String style = config.getStyle(); - tpl.binding(TemplateVariable.STYLE.getVariable(),style); + tpl.binding(TemplateVariable.STYLE.getVariable(), style); tpl.binding(TemplateVariable.BACKGROUND.getVariable(), HighlightStyle.getBackgroundColor(style)); tpl.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); tpl.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), errorCodeList); tpl.binding(TemplateVariable.VERSION_LIST.getVariable(), config.getRevisionLogs()); tpl.binding(TemplateVariable.VERSION.getVariable(), now); + tpl.binding(TemplateVariable.CREATE_TIME.getVariable(), strTime); tpl.binding(TemplateVariable.PROJECT_NAME.getVariable(), config.getProjectName()); tpl.binding(TemplateVariable.REQUEST_EXAMPLE.getVariable(), config.isRequestExample()); @@ -119,6 +135,11 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate { } else { tpl.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 2); } + if (Objects.nonNull(apiDoc)) { + tpl.binding(TemplateVariable.DESC.getVariable(), apiDoc.getDesc()); + tpl.binding(TemplateVariable.ORDER.getVariable(), apiDoc.order); + tpl.binding(TemplateVariable.LIST.getVariable(), apiDoc.getList());//类名 + } setDirectoryLanguageVariable(config, tpl); List apiDocDictList = buildDictionary(config, javaProjectBuilder); tpl.binding(TemplateVariable.DICT_LIST.getVariable(), apiDocDictList); @@ -140,6 +161,65 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate { FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName); } + /** + * build error_code html + * + * @param config api config + * @param apiDocList list data of Api doc + * @param template template + * @param outPutFileName output file + */ + public void buildErrorCodeDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder, + List apiDocList, String template, String outPutFileName) { + List errorCodeList = errorCodeDictToList(config); + Template errorTemplate = BeetlTemplateUtil.getByName(template); + errorTemplate.binding(TemplateVariable.PROJECT_NAME.getVariable(), config.getProjectName()); + String style = config.getStyle(); + errorTemplate.binding(TemplateVariable.STYLE.getVariable(), style); + if (CollectionUtil.isEmpty(errorCodeList)) { + errorTemplate.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 1); + } else { + errorTemplate.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 2); + } + List apiDocDictList = buildDictionary(config, javaProjectBuilder); + errorTemplate.binding(TemplateVariable.DICT_LIST.getVariable(), apiDocDictList); + errorTemplate.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); + errorTemplate.binding(TemplateVariable.BACKGROUND.getVariable(), HighlightStyle.getBackgroundColor(style)); + errorTemplate.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), errorCodeList); + setDirectoryLanguageVariable(config, errorTemplate); + FileUtil.nioWriteFile(errorTemplate.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName); + + } + + /** + * build common_data doc + * + * @param config api config + * @param javaProjectBuilder JavaProjectBuilder + * @param apiDocList list data of Api doc + * @param template template + * @param outPutFileName output file + */ + public void buildDirectoryDataDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder, List apiDocList, String template, String outPutFileName) { + List directoryList = buildDictionary(config, javaProjectBuilder); + Template mapper = BeetlTemplateUtil.getByName(template); + mapper.binding(TemplateVariable.PROJECT_NAME.getVariable(), config.getProjectName()); + String style = config.getStyle(); + mapper.binding(TemplateVariable.STYLE.getVariable(), style); + List errorCodeList = errorCodeDictToList(config); + if (CollectionUtil.isEmpty(errorCodeList)) { + mapper.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 1); + } else { + mapper.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 2); + } + mapper.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); + mapper.binding(TemplateVariable.BACKGROUND.getVariable(), HighlightStyle.getBackgroundColor(style)); + mapper.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), errorCodeList); + setDirectoryLanguageVariable(config, mapper); + mapper.binding(TemplateVariable.DICT_LIST.getVariable(), directoryList); + FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName); + } + /** * build common_data doc * diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index 2381430..3973637 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -22,27 +22,18 @@ */ 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.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.ApiDocDict; -import com.power.doc.model.ApiErrorCode; import com.power.doc.template.IDocBuildTemplate; import com.power.doc.template.SpringBootDocBuildTemplate; import com.power.doc.utils.BeetlTemplateUtil; -import com.power.doc.utils.MarkDownUtil; import com.thoughtworks.qdox.JavaProjectBuilder; import org.apache.commons.lang3.StringUtils; import org.beetl.core.Template; -import java.util.HashMap; import java.util.List; -import java.util.Map; import static com.power.doc.constants.DocGlobalConstants.*; @@ -94,125 +85,33 @@ public class HtmlApiDocBuilder { builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_HTML_TPL, INDEX_HTML); } } else { - List apiDocDictList = builderTemplate.buildDictionary(config, javaProjectBuilder); - buildIndex(apiDocList, config); - copyCss(config.getOutPath()); - buildDoc(apiDocList, config); - buildErrorCodeDoc(config.getErrorCodes(), config.getOutPath()); - buildDictionary(apiDocDictList, config.getOutPath()); + Template indexCssTemplate = BeetlTemplateUtil.getByName(ALL_IN_ONE_CSS); + FileUtil.nioWriteFile(indexCssTemplate.render(), config.getOutPath() + FILE_SEPARATOR + ALL_IN_ONE_CSS); + buildDoc(builderTemplate,apiDocList,config,javaProjectBuilder); + builderTemplate.buildErrorCodeDoc(config,javaProjectBuilder,apiDocList, + "html/error.html","error.html"); + builderTemplate.buildDirectoryDataDoc(config,javaProjectBuilder,apiDocList, + "html/dict.html","dict.html"); } } - private static void copyCss(String outPath) { - Template indexCssTemplate = BeetlTemplateUtil.getByName(INDEX_CSS_TPL); - Template mdCssTemplate = BeetlTemplateUtil.getByName(MARKDOWN_CSS_TPL); - FileUtil.nioWriteFile(indexCssTemplate.render(), outPath + FILE_SEPARATOR + INDEX_CSS_TPL); - 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); - if (CollectionUtil.isEmpty(apiDocList)) { - return; - } - ApiDoc doc = apiDocList.get(0); - String homePage = doc.getAlias(); - indexTemplate.binding(TemplateVariable.HOME_PAGE.getVariable(), homePage); - indexTemplate.binding(TemplateVariable.VERSION.getVariable(), now); - indexTemplate.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList); - indexTemplate.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), config.getErrorCodes()); - indexTemplate.binding(TemplateVariable.DICT_LIST.getVariable(), config.getDataDictionaries()); - if (CollectionUtil.isEmpty(config.getErrorCodes())) { - indexTemplate.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 1); - } else { - indexTemplate.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 2); - } - if (null != config.getLanguage()) { - if (DocLanguage.CHINESE.code.equals(config.getLanguage().getCode())) { - indexTemplate.binding(TemplateVariable.ERROR_LIST_TITLE.getVariable(), ERROR_CODE_LIST_CN_TITLE); - indexTemplate.binding(TemplateVariable.DICT_LIST_TITLE.getVariable(), DocGlobalConstants.DICT_CN_TITLE); - } else { - indexTemplate.binding(TemplateVariable.ERROR_LIST_TITLE.getVariable(), ERROR_CODE_LIST_EN_TITLE); - indexTemplate.binding(TemplateVariable.DICT_LIST_TITLE.getVariable(), DocGlobalConstants.DICT_EN_TITLE); - } - } else { - indexTemplate.binding(TemplateVariable.ERROR_LIST_TITLE.getVariable(), ERROR_CODE_LIST_CN_TITLE); - indexTemplate.binding(TemplateVariable.DICT_LIST_TITLE.getVariable(), DocGlobalConstants.DICT_CN_TITLE); - } - FileUtil.nioWriteFile(indexTemplate.render(), config.getOutPath() + FILE_SEPARATOR + "api.html"); - } - /** * build ever controller api * * @param apiDocList list of api doc * @param config ApiConfig */ - private static void buildDoc(List apiDocList, ApiConfig config) { + private static void buildDoc(DocBuilderTemplate builderTemplate,List apiDocList, + ApiConfig config,JavaProjectBuilder javaProjectBuilder) { FileUtil.mkdirs(config.getOutPath()); - Template htmlApiDoc; + int index = 0; for (ApiDoc doc : apiDocList) { - Template apiTemplate = BeetlTemplateUtil.getByName(API_DOC_MD_TPL); - apiTemplate.binding(TemplateVariable.REQUEST_EXAMPLE.getVariable(), config.isRequestExample()); - apiTemplate.binding(TemplateVariable.RESPONSE_EXAMPLE.getVariable(), config.isResponseExample()); - apiTemplate.binding(TemplateVariable.DESC.getVariable(), doc.getDesc()); - apiTemplate.binding(TemplateVariable.NAME.getVariable(), doc.getName()); - apiTemplate.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名 - Map templateVariables = new HashMap<>(); - templateVariables.put(TemplateVariable.TITLE.getVariable(), doc.getDesc()); - htmlApiDoc = initTemplate(apiTemplate, HTML_API_DOC_TPL, templateVariables); - FileUtil.nioWriteFile(htmlApiDoc.render(), config.getOutPath() + FILE_SEPARATOR + doc.getAlias() + ".html"); + if(index == 0){ + doc.setAlias("api"); + } + builderTemplate.buildDoc(apiDocList,config,javaProjectBuilder,"html/index.html", + doc.getAlias() + ".html",doc); + index ++; } } - - /** - * 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 errorTemplate = BeetlTemplateUtil.getByName(ERROR_CODE_LIST_MD_TPL); - errorTemplate.binding(TemplateVariable.LIST.getVariable(), errorCodeList); - Map templateVariables = new HashMap<>(); - templateVariables.put(TemplateVariable.TITLE.getVariable(), ERROR_CODE_LIST_EN_TITLE); - Template errorCodeDoc = initTemplate(errorTemplate, HTML_API_DOC_TPL, templateVariables); - FileUtil.nioWriteFile(errorCodeDoc.render(), outPath + FILE_SEPARATOR + "error_code.html"); - } - } - - /** - * build dictionary - * - * @param apiDocDictList dictionary list - * @param outPath - */ - private static void buildDictionary(List apiDocDictList, String outPath) { - if (CollectionUtil.isNotEmpty(apiDocDictList)) { - Template template = BeetlTemplateUtil.getByName(DICT_LIST_MD_TPL); - template.binding(TemplateVariable.DICT_LIST.getVariable(), apiDocDictList); - Map templateVariables = new HashMap<>(); - templateVariables.put(TemplateVariable.TITLE.getVariable(), DICT_EN_TITLE); - Template dictTpl = initTemplate(template, HTML_API_DOC_TPL, templateVariables); - FileUtil.nioWriteFile(dictTpl.render(), outPath + FILE_SEPARATOR + "dict.html"); - } - } - - private static Template initTemplate(Template template, String templateName, Map templateVariables) { - String errorHtml = MarkDownUtil.toHtml(template.render()); - Template template1 = BeetlTemplateUtil.getByName(templateName); - template1.binding(TemplateVariable.VERSION.getVariable(), now); - template1.binding(TemplateVariable.HTML.getVariable(), errorHtml); - template1.binding(TemplateVariable.CREATE_TIME.getVariable(), STR_TIME); - template1.binding(templateVariables); - return template1; - } } diff --git a/src/main/java/com/power/doc/constants/DocGlobalConstants.java b/src/main/java/com/power/doc/constants/DocGlobalConstants.java index f4fc80d..3984ece 100644 --- a/src/main/java/com/power/doc/constants/DocGlobalConstants.java +++ b/src/main/java/com/power/doc/constants/DocGlobalConstants.java @@ -5,6 +5,7 @@ package com.power.doc.constants; */ public interface DocGlobalConstants { + int API_ORDER = 0; String FILE_SEPARATOR = System.getProperty("file.separator"); String HTML_DOC_OUT_PATH = "src/main/resources/static/doc"; diff --git a/src/main/java/com/power/doc/constants/TemplateVariable.java b/src/main/java/com/power/doc/constants/TemplateVariable.java index 733eb4b..0c3e9f8 100644 --- a/src/main/java/com/power/doc/constants/TemplateVariable.java +++ b/src/main/java/com/power/doc/constants/TemplateVariable.java @@ -51,7 +51,8 @@ public enum TemplateVariable { RPC_CONSUMER_CONFIG("consumerConfigExample"), REQUEST_EXAMPLE("isRequestExample"), RESPONSE_EXAMPLE("isResponseExample"), - RESPONSE_LIST("respList"); + RESPONSE_LIST("respList"), + ORDER("order"); private String variable; diff --git a/src/main/java/com/power/doc/utils/DocUtil.java b/src/main/java/com/power/doc/utils/DocUtil.java index 7688ef5..932cbe6 100644 --- a/src/main/java/com/power/doc/utils/DocUtil.java +++ b/src/main/java/com/power/doc/utils/DocUtil.java @@ -507,7 +507,7 @@ public class DocUtil { return url.toString(); } else { url = annotation.getNamedParameter(DocAnnotationConstants.PATH_PROP); - return null == url ? StringUtil.ENMPTY : url.toString(); + return null == url ? StringUtil.EMPTY : url.toString(); } } } diff --git a/src/main/resources/template/html/dict.html b/src/main/resources/template/html/dict.html new file mode 100644 index 0000000..a7ab48d --- /dev/null +++ b/src/main/resources/template/html/dict.html @@ -0,0 +1,131 @@ + + + + + + + SpringBoot2-Open-Api + + + + + + + + + +
+ <%if(isNotEmpty(dictList)){%> +

${dictListOrder}. ${dictListTitle} +

+
<% for(dict in dictList){ %> +

${dictListOrder}.${dict.order}. ${dict.title} +

+ + + + + + + + + + + + + + <%for(dataDict in dict.dataDictList){%> + + + + + + <%}%> + +
CodeTypeDescription

${dataDict.value}

${dataDict.type}

${dataDict.desc}

+
+ <%}%> +
+
+ <%}%> +
Generated by smart-doc at 2020-12-15 00:22:14Suggestions,contact,support and error reporting on Gitee or Github
+
+ + + diff --git a/src/main/resources/template/html/error.html b/src/main/resources/template/html/error.html new file mode 100644 index 0000000..2f869a0 --- /dev/null +++ b/src/main/resources/template/html/error.html @@ -0,0 +1,125 @@ + + + + + + + SpringBoot2-Open-Api + + + + + + + + + +
+ <%if(isNotEmpty(errorCodeList)){%> +

${apiDocList.~size+1}. ${errorListTitle} +

+
+ + + + + + + + + + + + <%for(error in errorCodeList){%> + + + + + <%}%> + +
Error codeDescription

${error.value}

${error.desc}

+
+
+ <%}%> +
Generated by smart-doc at 2020-12-15 00:22:14Suggestions,contact,support and error reporting on Gitee or Github +
+
+ + + diff --git a/src/main/resources/template/html/index.html b/src/main/resources/template/html/index.html new file mode 100644 index 0000000..a9211bc --- /dev/null +++ b/src/main/resources/template/html/index.html @@ -0,0 +1,299 @@ + + + + + + + <%if(isNotEmpty(projectName)){%>${projectName}<%}else{%>API Reference<%}%> + + + + + + + + + +
+

${order}. ${desc} +

+
+ <%for(doc in list){%> +

<%if(doc.deprecated){%>${order}.${doc.order}. ${doc.desc}<%}else{%>${order}.${doc.order}. ${doc.desc}<%}%> +

+

URL: ${doc.url} +

+

Type: ${doc.type}

+ <%if(isNotEmpty(doc.author)){%> +

Author: ${doc.author}

+ <%}%> +

Content-Type: ${doc.contentType}

+

Description: ${doc.detail}

+ <%if(isNotEmpty(doc.requestHeaders)){%> +

Request-headers:

+ + + + + + + + + + + + + + + + + + <%for(header in doc.requestHeaders){%> + + + + + + + + <%}%> + +
HeaderTypeDescriptionRequiredSince

${header.name}

${header.type}

${header.desc}

${header.required}

${header.since}

+ <%}%><%if(isNotEmpty(doc.pathParams)){%> +

Path-parameters:

+ + + + + + + + + + + + + + + + + + <%for(param in doc.pathParams){%> + + + + + + + + <%}%> + +
ParameterTypeDescriptionRequiredSince

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

+ <%}%><%if(isNotEmpty(doc.queryParams)){%> +

Query-parameters:

+ + + + + + + + + + + + + + + + + + <%for(param in doc.queryParams){%> + + + + + + + + <%}%> + +
ParameterTypeDescriptionRequiredSince

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

+ <%}%><%if(isNotEmpty(doc.requestParams)){%> +

Body-parameters:

+ + + + + + + + + + + + + + + + + + <%for(param in doc.requestParams){%> + + + + + + + + <%}%> + +
ParameterTypeDescriptionRequiredSince

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

+ <%}%><%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%> +

Request-example:

+
+
+ 
${doc.requestUsage}
+
+
+ <%}%><%if(isNotEmpty(doc.responseParams)){%> +

Response-fields:

+ + + + + + + + + + + + + + + + <%for(param in doc.responseParams){%> + + + + + + + <%}%> + +
FieldTypeDescriptionSince

${param.field}

${param.type}

${param.desc}

${param.version}

+ <%}%><%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%> +

Response-example:

+
+
+ 
${doc.responseUsage}
+
+
+ <%}%> +
+ <%}%> +
+
+
+
Generated by smart-doc at 2020-12-15 00:22:14Suggestions,contact,support and error reporting on Gitee or Github
+ + + +