From 7140760a2b8dda46ff98ee7f17b8469d209ca1c9 Mon Sep 17 00:00:00 2001 From: oppofind <836575280@qq.com> Date: Sun, 17 May 2020 21:58:41 +0800 Subject: [PATCH] add dubbo adoc template --- .../com/power/doc/builder/AdocDocBuilder.java | 2 +- .../com/power/doc/builder/ApiDocBuilder.java | 2 +- .../power/doc/builder/HtmlApiDocBuilder.java | 2 +- .../power/doc/builder/PostmanJsonBuilder.java | 2 +- .../power/doc/builder/rpc/RpcAdocBuilder.java | 53 ++++ .../doc/builder/rpc/RpcMarkdownBuilder.java | 2 +- .../doc/constants/DocGlobalConstants.java | 12 +- src/main/resources/template/dubbo/Dubbo.adoc | 60 ++++ .../resources/template/{ => dubbo}/Dubbo.md | 0 .../template/dubbo/DubboAllInOne.adoc | 111 +++++++ .../template/dubbo/DubboAllInOne.html | 295 ++++++++++++++++++ .../DubboAllInOne.md} | 0 12 files changed, 532 insertions(+), 9 deletions(-) create mode 100644 src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java create mode 100644 src/main/resources/template/dubbo/Dubbo.adoc rename src/main/resources/template/{ => dubbo}/Dubbo.md (100%) create mode 100644 src/main/resources/template/dubbo/DubboAllInOne.adoc create mode 100644 src/main/resources/template/dubbo/DubboAllInOne.html rename src/main/resources/template/{DubboAllIneOne.md => dubbo/DubboAllInOne.md} (100%) diff --git a/src/main/java/com/power/doc/builder/AdocDocBuilder.java b/src/main/java/com/power/doc/builder/AdocDocBuilder.java index 73b21ae..c119aae 100644 --- a/src/main/java/com/power/doc/builder/AdocDocBuilder.java +++ b/src/main/java/com/power/doc/builder/AdocDocBuilder.java @@ -54,7 +54,7 @@ public class AdocDocBuilder { } /** - * Only for smart-doc-maven-plugin. + * Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder diff --git a/src/main/java/com/power/doc/builder/ApiDocBuilder.java b/src/main/java/com/power/doc/builder/ApiDocBuilder.java index 28f7eb6..8becc4b 100644 --- a/src/main/java/com/power/doc/builder/ApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/ApiDocBuilder.java @@ -53,7 +53,7 @@ public class ApiDocBuilder { } /** - * Only for smart-doc-maven-plugin. + * Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index edc8789..a116355 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -65,7 +65,7 @@ public class HtmlApiDocBuilder { } /** - * Only for smart-doc-maven-plugin. + * Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder diff --git a/src/main/java/com/power/doc/builder/PostmanJsonBuilder.java b/src/main/java/com/power/doc/builder/PostmanJsonBuilder.java index 0cc495a..0838f86 100644 --- a/src/main/java/com/power/doc/builder/PostmanJsonBuilder.java +++ b/src/main/java/com/power/doc/builder/PostmanJsonBuilder.java @@ -65,7 +65,7 @@ public class PostmanJsonBuilder { } /** - * Only for smart-doc-maven-plugin. + * Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig Object * @param projectBuilder QDOX avaProjectBuilder diff --git a/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java new file mode 100644 index 0000000..6139ab8 --- /dev/null +++ b/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java @@ -0,0 +1,53 @@ +package com.power.doc.builder.rpc; + +import com.power.doc.builder.ProjectDocConfigBuilder; +import com.power.doc.model.ApiConfig; +import com.power.doc.model.rpc.RpcApiDoc; +import com.power.doc.template.JavaDocBuildTemplate; +import com.thoughtworks.qdox.JavaProjectBuilder; + +import java.util.List; + +import static com.power.doc.constants.DocGlobalConstants.*; + +/** + * @author yu 2020/5/17. + */ +public class RpcAdocBuilder { + + private static final String API_EXTENSION = "RpcApi.adoc"; + + private static final String INDEX_DOC = "rpc-index.adoc"; + + /** + * build adoc + * + * @param config ApiConfig + */ + public static void builderApiDoc(ApiConfig config) { + JavaProjectBuilder javaProjectBuilder = new JavaProjectBuilder(); + buildApiDoc(config, javaProjectBuilder); + } + + /** + * Only for smart-doc maven plugin and gradle plugin. + * + * @param config ApiConfig + * @param javaProjectBuilder ProjectDocConfigBuilder + */ + public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) { + config.setAdoc(true); + RpcDocBuilderTemplate builderTemplate = new RpcDocBuilderTemplate(); + builderTemplate.checkAndInit(config); + ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder); + JavaDocBuildTemplate docBuildTemplate = new JavaDocBuildTemplate(); + List apiDocList = docBuildTemplate.getApiData(configBuilder); + if (config.isAllInOne()) { + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, RPC_ALL_IN_ONE_ADOC_TPL, INDEX_DOC); + } else { + builderTemplate.buildApiDoc(apiDocList, config, RPC_API_DOC_ADOC_TPL, API_EXTENSION); + builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC); + } + } + +} diff --git a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java index 8b27b18..9b08b1f 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java @@ -29,7 +29,7 @@ public class RpcMarkdownBuilder { } /** - * Only for smart-doc-maven-plugin. + *Only for smart-doc maven plugin and gradle plugin. * * @param config ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder diff --git a/src/main/java/com/power/doc/constants/DocGlobalConstants.java b/src/main/java/com/power/doc/constants/DocGlobalConstants.java index 0eef8dd..c6c4c78 100644 --- a/src/main/java/com/power/doc/constants/DocGlobalConstants.java +++ b/src/main/java/com/power/doc/constants/DocGlobalConstants.java @@ -21,21 +21,25 @@ public interface DocGlobalConstants { String API_DOC_ADOC_TPL = "ApiDoc.adoc"; + String RPC_API_DOC_ADOC_TPL = "dubbo/Dubbo.adoc"; + String ALL_IN_ONE_MD_TPL = "AllInOne.btl"; String ALL_IN_ONE_ADOC_TPL = "AllInOne.adoc"; + String RPC_ALL_IN_ONE_ADOC_TPL = "dubbo/DubboAllInOne.adoc"; + String ALL_IN_ONE_HTML_TPL = "AllInOne.html"; String HTML_API_DOC_TPL = "HtmlApiDoc.btl"; String ERROR_CODE_LIST_MD_TPL = "ErrorCodeList.btl"; - String ERROR_CODE_LIST_ADOC_TPL = "ErrorCodeList.btl"; + String ERROR_CODE_LIST_ADOC_TPL = "ErrorCodeList.adoc"; String ERROR_CODE_LIST_MD = "ErrorCodeList.md"; - String ERROR_CODE_LIST_ADOC = "ErrorCodeList.md"; + String ERROR_CODE_LIST_ADOC = "ErrorCodeList.adoc"; String DICT_LIST_MD = "Dictionary.md"; @@ -53,9 +57,9 @@ public interface DocGlobalConstants { String ALL_IN_ONE_CSS = "AllInOne.css"; - String RPC_API_DOC_MD_TPL = "Dubbo.md"; + String RPC_API_DOC_MD_TPL = "dubbo/Dubbo.md"; - String RPC_ALL_IN_ONE_MD_TPL = "DubboAllIneOne.md"; + String RPC_ALL_IN_ONE_MD_TPL = "dubbo/DubboAllInOne.md"; String POSTMAN_JSON = "/postman.json"; diff --git a/src/main/resources/template/dubbo/Dubbo.adoc b/src/main/resources/template/dubbo/Dubbo.adoc new file mode 100644 index 0000000..90e44fa --- /dev/null +++ b/src/main/resources/template/dubbo/Dubbo.adoc @@ -0,0 +1,60 @@ + += ${desc} + +*URI:* ${uri} + +*Service:* ${name} + +*Protocol:* ${protocol} + +*Author:* ${author} + +*Version:* ${version} +<% +for(doc in list){ +%> +<%if(doc.deprecated){%> +== ~~${doc.desc}~~ +<%}else{%> +## ${doc.desc} +<%}%> + +*Definition：* ${doc.methodDefinition} + +<%if(isNotEmpty(doc.author)){%> +*Author:* ${doc.author} +<%}%> + +*Description:* ${doc.detail} + +<%if(isNotEmpty(doc.requestParams)){%> +*Request-parameters:* + +[width="100%",options="header"] +[stripes=even] +|==================== +|Parameter | Type|Description|Required|Since +<% +for(param in doc.requestParams){ +%> +|${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} +<%}%> +|==================== +<%}%> + +<%if(isNotEmpty(doc.responseParams)){%> +*Response-fields:* + +[width="100%",options="header"] +[stripes=even] +|==================== +|Field | Type|Description|Since +<% +for(param in doc.responseParams){ +%> +|${param.field}|${param.type}|${param.desc}|${param.version} +<%}%> +|==================== +<%}%> + +<% } %> \ No newline at end of file diff --git a/src/main/resources/template/Dubbo.md b/src/main/resources/template/dubbo/Dubbo.md similarity index 100% rename from src/main/resources/template/Dubbo.md rename to src/main/resources/template/dubbo/Dubbo.md diff --git a/src/main/resources/template/dubbo/DubboAllInOne.adoc b/src/main/resources/template/dubbo/DubboAllInOne.adoc new file mode 100644 index 0000000..4c653ad --- /dev/null +++ b/src/main/resources/template/dubbo/DubboAllInOne.adoc @@ -0,0 +1,111 @@ +<%if(isNotEmpty(projectName)){%> += ${projectName} +<%}%> + +<%if(isNotEmpty(revisionLogList)){%> +[width="100%",options="header"] +[stripes=even] +|==================== +|Version | Update Time | Status | Author | Description +<% +for(revisionLog in revisionLogList){ +%> +${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks} +<%}%> +|==================== +<%}%> + +<%if(isNotEmpty(dependencyList)){%> +== Add dependency + +---- +<% +for(dependency in dependencyList){ +%> + + ${dependency.groupId} + ${dependency.artifactId} + ${dependency.version} + + +<%}%> +---- +<%}%> + +<% +for(api in apiDocList){ +%> +== ${api.desc} + +*URI:* ${api.uri} + +*Service:* ${api.name} + +*Protocol:* ${api.protocol} + +*Author:* ${api.author} + +*Version:* ${api.version} +<% +for(doc in api.list){ +%> +<%if(doc.deprecated){%> +=== ~~${doc.desc}~~ +<%}else{%> +=== ${doc.desc} +<%}%> + +*Definition：* ${doc.methodDefinition} + +<%if(isNotEmpty(doc.author)){%> +*Author:* ${doc.author} +<%}%> + +*Description:* ${doc.detail} + +<%if(isNotEmpty(doc.requestParams)){%> +*Request-parameters:* + +[width="100%",options="header"] +[stripes=even] +|==================== +|Parameter | Type|Description|Required|Since +<% +for(param in doc.requestParams){ +%> +${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} +<%}%> +|==================== +<%}%> + +<%if(isNotEmpty(doc.responseParams)){%> +*Response-fields:* + +[width="100%",options="header"] +[stripes=even] +|==================== +|Field | Type|Description|Since +<% +for(param in doc.responseParams){ +%> +${param.field}|${param.type}|${param.desc}|${param.version} +<%}%> +|==================== +<%}%> + +<%if(isNotEmpty(errorCodeList)){%> +== ${errorListTitle} +[width="100%",options="header"] +[stripes=even] +|==================== +|Error code |Description +<% +for(error in errorCodeList){ +%> +${error.value}|${error.desc} +<%}%> +|==================== +<%}%> + +<%}%> +<%}%> \ No newline at end of file diff --git a/src/main/resources/template/dubbo/DubboAllInOne.html b/src/main/resources/template/dubbo/DubboAllInOne.html new file mode 100644 index 0000000..45a2f2b --- /dev/null +++ b/src/main/resources/template/dubbo/DubboAllInOne.html @@ -0,0 +1,295 @@ + + + + + + + <%if(isNotEmpty(projectName)){%>${projectName}<%}else{%>API Reference<%}%> + + + + + + +
<%if(isNotEmpty(revisionLogList)){%> +
+
+ + + + + + + + + + + + + + + + + + <%for(revisionLog in revisionLogList){%> + + + + + + + + <%}%> + +
VersionUpdate TimeStatusAuthorDescription

${revisionLog.version}

${revisionLog.revisionTime}

+

${revisionLog.status}

${revisionLog.author}

${revisionLog.remarks}

+
+
+ <%}%><%for(api in apiDocList){%> +

${api.order}. ${api.desc} +

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

<%if(doc.deprecated){%>${api.order}.${doc.order}. ${doc.desc}<%}else{%>${api.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.requestParams)){%> +

Request-parameters:

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

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

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

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)){%> +

Response-example:

+
+
+ 
${doc.responseUsage}
+
+
+ <%}%> +
+ <%}%> +
+
+ <%}%><%if(isNotEmpty(errorCodeList)){%> +

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

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

${error.value}

${error.desc}

+
+
+ <%}%><%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 ${createTime}Suggestions,contact,support and error reporting on Gitee or Github
+
+ + + \ No newline at end of file diff --git a/src/main/resources/template/DubboAllIneOne.md b/src/main/resources/template/dubbo/DubboAllInOne.md similarity index 100% rename from src/main/resources/template/DubboAllIneOne.md rename to src/main/resources/template/dubbo/DubboAllInOne.md