wanjia950611
/
smart-doc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

and adoc support

This commit is contained in:
oppofind 2019-09-27 00:09:37 +08:00
parent 71ab880ee5
commit 66b30b8abb
5 changed files with 150 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
src/main/java/com/power/doc/builder/AdocDocBuilder.java Normal file
View File

@ -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<ApiDoc> 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);
}
}
}

106
src/main/java/com/power/doc/builder/ApiDocBuilder.java
View File

@ -1,17 +1,8 @@
package com.power.doc.builder; package com.power.doc.builder;
import com.power.common.util.CollectionUtil;
import com.power.common.util.DateTimeUtil; 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.ApiConfig;
import com.power.doc.model.ApiDoc; 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 java.util.List;
@ -24,105 +15,26 @@ import static com.power.doc.constants.DocGlobalConstants.*;
*/ */
public class ApiDocBuilder { public class ApiDocBuilder {
/** private static final String API_EXTENSION = "Api.md";
* Generate api documentation for all controllers.
* If set to strict mode, smart-doc will check the method comments on each controller. private static final String DATE_FORMAT = "yyyyMMddHHmm";
* @param outPath output path
* @param isStrict is use strict mode
*/
public static void builderControllersApi(String outPath, boolean isStrict) {
SourceBuilder sourceBuilder = new SourceBuilder(isStrict);
List<ApiDoc> apiDocList = sourceBuilder.getControllerApiData();
buildApiDoc(apiDocList, outPath);
}
/** /**
* @param config ApiConfig * @param config ApiConfig
*/ */
public static void builderControllersApi(ApiConfig config) { public static void builderControllersApi(ApiConfig config) {
if (null == config) { BuilderTemplate builderTemplate = new BuilderTemplate();
throw new NullPointerException("ApiConfig can't be null"); builderTemplate.checkAndInit(config);
}
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());
}
SourceBuilder sourceBuilder = new SourceBuilder(config); SourceBuilder sourceBuilder = new SourceBuilder(config);
List<ApiDoc> apiDocList = sourceBuilder.getControllerApiData(); List<ApiDoc> apiDocList = sourceBuilder.getControllerApiData();
if (config.isAllInOne()) { 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 { } else {
buildApiDoc(apiDocList, config.getOutPath()); builderTemplate.buildApiDoc(apiDocList,config,API_DOC_MD_TPL,API_EXTENSION);
buildErrorCodeDoc(config.getErrorCodes(), config.getOutPath()); 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<ApiDoc> 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<ApiDoc> 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<ApiErrorCode> 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);
}
}
} }

92
src/main/java/com/power/doc/builder/BuilderTemplate.java Normal file
View File

@ -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<ApiDoc> 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<ApiDoc> 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<ApiErrorCode> 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);
}
}
}

4
src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java
View File

@ -95,7 +95,7 @@ public class HtmlApiDocBuilder {
Template htmlApiDoc; Template htmlApiDoc;
String strTime = DateTimeUtil.long2Str(now, DateTimeUtil.DATE_FORMAT_SECOND); String strTime = DateTimeUtil.long2Str(now, DateTimeUtil.DATE_FORMAT_SECOND);
for (ApiDoc doc : apiDocList) { 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.DESC.getVariable(), doc.getDesc());
apiTemplate.binding(TemplateVariable.NAME.getVariable(), doc.getName()); apiTemplate.binding(TemplateVariable.NAME.getVariable(), doc.getName());
apiTemplate.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名 apiTemplate.binding(TemplateVariable.LIST.getVariable(), doc.getList());//类名
@ -118,7 +118,7 @@ public class HtmlApiDocBuilder {
*/ */
private static void buildErrorCodeDoc(List<ApiErrorCode> errorCodeList, String outPath) { private static void buildErrorCodeDoc(List<ApiErrorCode> errorCodeList, String outPath) {
if (CollectionUtil.isNotEmpty(errorCodeList)) { 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); error.binding(TemplateVariable.LIST.getVariable(), errorCodeList);
String errorHtml = MarkDownUtil.toHtml(error.render()); String errorHtml = MarkDownUtil.toHtml(error.render());
Template errorCodeDoc = BeetlTemplateUtil.getByName(HTML_API_DOC_TPL); Template errorCodeDoc = BeetlTemplateUtil.getByName(HTML_API_DOC_TPL);

14
src/main/java/com/power/doc/constants/DocGlobalConstants.java
View File

@ -13,14 +13,24 @@ public class DocGlobalConstants {
public static final String DOC_LANGUAGE = "smart-doc_language"; 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 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_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_TPL = "Index.btl";
public static final String INDEX_CSS_TPL = "index.css"; public static final String INDEX_CSS_TPL = "index.css";