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

add data return api

This commit is contained in:
oppofind 2019-09-27 23:42:56 +08:00
parent 59e9d574c1
commit 3824c1a60d
21 changed files with 413 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/main/java/com/power/doc/builder/AdocDocBuilder.java
View File

@ -9,6 +9,7 @@ import static com.power.doc.constants.DocGlobalConstants.*;
/** /**
* Use to create Asciidoc * Use to create Asciidoc
*
* @author yu 2019/9/26. * @author yu 2019/9/26.
*/ */
public class AdocDocBuilder { public class AdocDocBuilder {
@ -17,10 +18,13 @@ public class AdocDocBuilder {
private static final String INDEX_DOC = "index.adoc"; private static final String INDEX_DOC = "index.adoc";
/** build adoc /**
* build adoc
*
* @param config ApiConfig * @param config ApiConfig
*/ */
public static void builderControllersApi(ApiConfig config) { public static void builderControllersApi(ApiConfig config) {
config.setAdoc(true);
DocBuilderTemplate builderTemplate = new DocBuilderTemplate(); DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config); builderTemplate.checkAndInit(config);
SourceBuilder sourceBuilder = new SourceBuilder(config); SourceBuilder sourceBuilder = new SourceBuilder(config);
@ -32,4 +36,16 @@ public class AdocDocBuilder {
builderTemplate.buildErrorCodeDoc(config.getErrorCodes(), config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC); builderTemplate.buildErrorCodeDoc(config.getErrorCodes(), config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC);
} }
} }
/**
* Generate a single controller api document
*
* @param config ApiConfig
* @param controllerName controller name
*/
public static void buildSingleControllerApi(ApiConfig config, String controllerName) {
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config);
builderTemplate.buildSingleControllerApi(config.getOutPath(), controllerName, API_DOC_ADOC_TPL, API_EXTENSION);
}
} }

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

@ -23,6 +23,7 @@ public class ApiDocBuilder {
* @param config ApiConfig * @param config ApiConfig
*/ */
public static void builderControllersApi(ApiConfig config) { public static void builderControllersApi(ApiConfig config) {
config.setAdoc(false);
DocBuilderTemplate builderTemplate = new DocBuilderTemplate(); DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config); builderTemplate.checkAndInit(config);
SourceBuilder sourceBuilder = new SourceBuilder(config); SourceBuilder sourceBuilder = new SourceBuilder(config);
@ -36,5 +37,41 @@ public class ApiDocBuilder {
} }
} }
/**
* Generate a single controller api document
*
* @param config (ApiConfig
* @param controllerName controller name
*/
public static void buildSingleControllerApi(ApiConfig config, String controllerName) {
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config);
builderTemplate.buildSingleControllerApi(config.getOutPath(), controllerName, API_DOC_MD_TPL, API_EXTENSION);
}
/**
* @param config
* @return
*/
public static List<ApiDoc> listOfApiData(ApiConfig config) {
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInitForGetApiData(config);
SourceBuilder sourceBuilder = new SourceBuilder(config);
return sourceBuilder.getControllerApiData();
}
/**
* Get single api data
*
* @param config ApiConfig
* @param controllerName controller name
* @return ApiDoc
*/
public static ApiDoc getApiData(ApiConfig config, String controllerName) {
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInitForGetApiData(config);
SourceBuilder sourceBuilder = new SourceBuilder(config);
return sourceBuilder.getSingleControllerApiData(controllerName);
}
} }

38
src/main/java/com/power/doc/builder/DocBuilderTemplate.java
View File

@ -42,6 +42,23 @@ public class DocBuilderTemplate {
} }
} }
/**
* check condition and init for get Data
*
* @param config Api config
*/
public void checkAndInitForGetApiData(ApiConfig config) {
if (null == config) {
throw new NullPointerException("ApiConfig can't be null");
}
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. * Generate api documentation for all controllers.
* *
@ -69,6 +86,7 @@ public class DocBuilderTemplate {
/** /**
* Merge all api doc into one document * Merge all api doc into one document
*
* @param apiDocList list data of Api doc * @param apiDocList list data of Api doc
* @param config api config * @param config api config
* @param template template * @param template template
@ -87,6 +105,7 @@ public class DocBuilderTemplate {
/** /**
* build error_code adoc * build error_code adoc
*
* @param errorCodeList list data of Api doc * @param errorCodeList list data of Api doc
* @param config api config * @param config api config
* @param template template * @param template template
@ -99,4 +118,23 @@ public class DocBuilderTemplate {
FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName); FileUtil.nioWriteFile(mapper.render(), config.getOutPath() + FILE_SEPARATOR + outPutFileName);
} }
} }
/**
* Generate a single controller api document
*
* @param outPath output path
* @param controllerName controller name
* @param template template
* @param fileExtension file extension
*/
public void buildSingleControllerApi(String outPath, String controllerName, String template, String fileExtension) {
FileUtil.mkdirs(outPath);
SourceBuilder sourceBuilder = new SourceBuilder(true);
ApiDoc doc = sourceBuilder.getSingleControllerApiData(controllerName);
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.writeFileNotAppend(mapper.render(), outPath + FILE_SEPARATOR + doc.getName() + fileExtension);
}
} }

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

@ -28,6 +28,7 @@ public class HtmlApiDocBuilder {
/** /**
* build controller api * build controller api
*
* @param config config * @param config config
*/ */
public static void builderControllersApi(ApiConfig config) { public static void builderControllersApi(ApiConfig config) {
@ -60,6 +61,7 @@ public class HtmlApiDocBuilder {
/** /**
* build api.html * build api.html
*
* @param apiDocList list of api doc * @param apiDocList list of api doc
* @param config ApiConfig * @param config ApiConfig
*/ */

289
src/main/java/com/power/doc/builder/SourceBuilder.java
View File

@ -51,6 +51,7 @@ public class SourceBuilder {
private List<ApiReqHeader> headers; private List<ApiReqHeader> headers;
private String appUrl; private String appUrl;
private boolean isUseMD5; private boolean isUseMD5;
private boolean isAdoc;
/** /**
* if isStrict value is true,it while check all method * if isStrict value is true,it while check all method
@ -81,7 +82,9 @@ public class SourceBuilder {
isUseMD5 = config.isMd5EncryptedHtmlName(); isUseMD5 = config.isMd5EncryptedHtmlName();
this.packageMatch = config.getPackageFilters(); this.packageMatch = config.getPackageFilters();
this.isStrict = config.isStrict(); this.isStrict = config.isStrict();
this.isAdoc = config.isAdoc();
loadJavaFiles(config.getSourceCodePaths()); loadJavaFiles(config.getSourceCodePaths());
this.headers = config.getRequestHeaders(); this.headers = config.getRequestHeaders();
if (CollectionUtil.isNotEmpty(config.getCustomResponseFields())) { if (CollectionUtil.isNotEmpty(config.getCustomResponseFields())) {
for (CustomRespField field : config.getCustomResponseFields()) { for (CustomRespField field : config.getCustomResponseFields()) {
@ -220,16 +223,18 @@ public class SourceBuilder {
apiMethodDoc.setType(methodType); apiMethodDoc.setType(methodType);
url = this.appUrl + "/" + baseUrl + "/" + url; url = this.appUrl + "/" + baseUrl + "/" + url;
apiMethodDoc.setUrl(UrlUtil.simplifyUrl(url)); apiMethodDoc.setUrl(UrlUtil.simplifyUrl(url));
String comment = getCommentTag(method, "param", cls.getCanonicalName()); List<ApiParam> requestParams = getCommentTag(method, "param", cls.getCanonicalName());
apiMethodDoc.setRequestParams(comment); apiMethodDoc.setRequestParams(requestParams);
String requestJson = buildReqJson(method, apiMethodDoc); String requestJson = buildReqJson(method, apiMethodDoc);
apiMethodDoc.setRequestUsage(JsonFormatUtil.formatJson(requestJson)); apiMethodDoc.setRequestUsage(JsonFormatUtil.formatJson(requestJson));
apiMethodDoc.setResponseUsage(buildReturnJson(method, this.fieldMap)); apiMethodDoc.setResponseUsage(buildReturnJson(method, this.fieldMap));
String str = buildMethodReturn(method, cls.getGenericFullyQualifiedName()); List<ApiParam> responseParams = buildMethodReturn(method, cls.getGenericFullyQualifiedName());
apiMethodDoc.setResponseParams(str); apiMethodDoc.setResponseParams(responseParams);
apiMethodDoc.setHeaders(createHeaders(this.headers)); //reduce create in template
apiMethodDoc.setHeaders(createHeaders(this.headers, this.isAdoc));
apiMethodDoc.setRequestHeaders(this.headers);
methodDocList.add(apiMethodDoc); methodDocList.add(apiMethodDoc);
} }
} }
@ -274,12 +279,15 @@ public class SourceBuilder {
* @param headers Api request headers * @param headers Api request headers
* @return headers * @return headers
*/ */
private String createHeaders(List<ApiReqHeader> headers) { private String createHeaders(List<ApiReqHeader> headers, boolean isAdoc) {
StringBuilder builder = new StringBuilder(); StringBuilder builder = new StringBuilder();
if (CollectionUtil.isEmpty(headers)) { if (CollectionUtil.isEmpty(headers)) {
headers = new ArrayList<>(0); headers = new ArrayList<>(0);
} }
for (ApiReqHeader header : headers) { for (ApiReqHeader header : headers) {
if (isAdoc) {
builder.append("|");
}
builder.append(header.getName()).append("|") builder.append(header.getName()).append("|")
.append(header.getType()).append("|") .append(header.getType()).append("|")
.append(header.getDesc()).append("|") .append(header.getDesc()).append("|")
@ -289,7 +297,7 @@ public class SourceBuilder {
return builder.toString(); return builder.toString();
} }
private String buildMethodReturn(JavaMethod method, String controllerName) { private List<ApiParam> buildMethodReturn(JavaMethod method, String controllerName) {
ApiReturn apiReturn = DocClassUtil.processReturnType(method.getReturnType().getGenericCanonicalName()); ApiReturn apiReturn = DocClassUtil.processReturnType(method.getReturnType().getGenericCanonicalName());
String returnType = apiReturn.getGenericCanonicalName(); String returnType = apiReturn.getGenericCanonicalName();
String typeName = apiReturn.getSimpleName(); String typeName = apiReturn.getSimpleName();
@ -309,8 +317,7 @@ public class SourceBuilder {
if (DocClassUtil.isPrimitive(gicName)) { if (DocClassUtil.isPrimitive(gicName)) {
return primitiveReturnRespComment("array of " + DocClassUtil.processTypeNameForParams(gicName)); return primitiveReturnRespComment("array of " + DocClassUtil.processTypeNameForParams(gicName));
} }
String param = buildParams(gicName, "", 0, null, fieldMap, true); return buildParams(gicName, "", 0, null, fieldMap, true);
return param;
} else { } else {
return null; return null;
} }
@ -323,12 +330,10 @@ public class SourceBuilder {
if (DocClassUtil.isPrimitive(keyValue[1])) { if (DocClassUtil.isPrimitive(keyValue[1])) {
return primitiveReturnRespComment("key value"); return primitiveReturnRespComment("key value");
} }
String param = buildParams(keyValue[1], "", 0, null, fieldMap, true); return buildParams(keyValue[1], "", 0, null, fieldMap, true);
return param;
} }
if (StringUtil.isNotEmpty(returnType)) { if (StringUtil.isNotEmpty(returnType)) {
String param = buildParams(returnType, "", 0, null, fieldMap, true); return buildParams(returnType, "", 0, null, fieldMap, true);
return param;
} }
return null; return null;
} }
@ -344,12 +349,13 @@ public class SourceBuilder {
* @param isResp response flag * @param isResp response flag
* @return params * @return params
*/ */
private String buildParams(String className, String pre, int i, String isRequired, private List<ApiParam> buildParams(String className, String pre, int i, String isRequired,
Map<String, CustomRespField> responseFieldMap, boolean isResp) { Map<String, CustomRespField> responseFieldMap, boolean isResp) {
if (StringUtil.isEmpty(className)) { if (StringUtil.isEmpty(className)) {
throw new RuntimeException("Class name can't be null or empty."); throw new RuntimeException("Class name can't be null or empty.");
} }
StringBuilder params0 = new StringBuilder(); StringBuilder params0 = new StringBuilder();
List<ApiParam> paramList = new ArrayList<>();
String simpleName = DocClassUtil.getSimpleName(className); String simpleName = DocClassUtil.getSimpleName(className);
@ -359,26 +365,34 @@ public class SourceBuilder {
List<JavaField> fields = getFields(cls, 0); List<JavaField> fields = getFields(cls, 0);
int n = 0; int n = 0;
if (DocClassUtil.isPrimitive(simpleName)) { if (DocClassUtil.isPrimitive(simpleName)) {
params0.append(primitiveReturnRespComment(DocClassUtil.processTypeNameForParams(simpleName))); paramList.addAll(primitiveReturnRespComment(DocClassUtil.processTypeNameForParams(simpleName)));
//params0.append(primitiveReturnRespComment(DocClassUtil.processTypeNameForParams(simpleName)));
} else if (DocClassUtil.isCollection(simpleName) || DocClassUtil.isArray(simpleName)) { } else if (DocClassUtil.isCollection(simpleName) || DocClassUtil.isArray(simpleName)) {
if (!DocClassUtil.isCollection(globGicName[0])) { if (!DocClassUtil.isCollection(globGicName[0])) {
String gicName = globGicName[0]; String gicName = globGicName[0];
if (DocClassUtil.isArray(gicName)) { if (DocClassUtil.isArray(gicName)) {
gicName = gicName.substring(0, gicName.indexOf("[")); gicName = gicName.substring(0, gicName.indexOf("["));
} }
params0.append(buildParams(gicName, pre, i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gicName, pre, i + 1, isRequired, responseFieldMap, isResp));
//params0.append(buildParams(gicName, pre, i + 1, isRequired, responseFieldMap, isResp));
} }
} else if (DocClassUtil.isMap(simpleName)) { } else if (DocClassUtil.isMap(simpleName)) {
if (globGicName.length == 2) { if (globGicName.length == 2) {
params0.append(buildParams(globGicName[1], pre, i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(globGicName[1], pre, i + 1, isRequired, responseFieldMap, isResp));
//params0.append(buildParams(globGicName[1], pre, i + 1, isRequired, responseFieldMap, isResp));
} }
} else if (DocGlobalConstants.JAVA_OBJECT_FULLY.equals(className)) { } else if (DocGlobalConstants.JAVA_OBJECT_FULLY.equals(className)) {
params0.append(pre + "any object|object|"); params0.append(pre + "any object|object|");
ApiParam param = ApiParam.of().setField(pre + "any object").setType("object");
if (StringUtil.isEmpty(isRequired)) { if (StringUtil.isEmpty(isRequired)) {
params0.append("any object.").append("|-\n"); param.setDesc("any object.").setVersion("-");
//params0.append("any object.").append("|-\n");
} else { } else {
params0.append("any object.").append("|").append(false).append("|-\n"); // params0.append("any object.").append("|").append(false).append("|-\n");
param.setDesc("any object.").setRequired(false).setVersion("-");
} }
paramList.add(param);
} else { } else {
out: out:
for (JavaField field : fields) { for (JavaField field : fields) {
@ -408,7 +422,8 @@ public class SourceBuilder {
} }
} }
} }
String strRequired = "false";
boolean strRequired = false;
int annotationCounter = 0; int annotationCounter = 0;
an: an:
for (JavaAnnotation annotation : javaAnnotations) { for (JavaAnnotation annotation : javaAnnotations) {
@ -428,7 +443,7 @@ public class SourceBuilder {
fieldName = annotation.getProperty("value").toString().replace("\"", ""); fieldName = annotation.getProperty("value").toString().replace("\"", "");
} }
} else if (DocClassUtil.isJSR303Required(annotationName)) { } else if (DocClassUtil.isJSR303Required(annotationName)) {
strRequired = "true"; strRequired = true;
annotationCounter++; annotationCounter++;
break an; break an;
} }
@ -437,7 +452,7 @@ public class SourceBuilder {
doc: doc:
for (DocletTag docletTag : paramTags) { for (DocletTag docletTag : paramTags) {
if (DocClassUtil.isRequiredTag(docletTag.getName())) { if (DocClassUtil.isRequiredTag(docletTag.getName())) {
strRequired = "true"; strRequired = true;
break doc; break doc;
} }
} }
@ -454,44 +469,29 @@ public class SourceBuilder {
comment = comment.replace("\n", "<br>"); comment = comment.replace("\n", "<br>");
} }
if (DocClassUtil.isPrimitive(subTypeName)) { if (DocClassUtil.isPrimitive(subTypeName)) {
params0.append(pre); ApiParam param = ApiParam.of().setField(pre + fieldName);
params0.append(fieldName).append("|") String processedType = DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase());
.append(DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase())).append("|"); param.setType(processedType);
// params0.append(pre);
// params0.append(fieldName).append("|")
// .append(DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase())).append("|");
if (StringUtil.isNotEmpty(comment)) { if (StringUtil.isNotEmpty(comment)) {
if (StringUtil.isEmpty(isRequired)) { commonHandleParam(paramList, param, isRequired, comment, since, strRequired);
params0.append(comment).append("|").append(since).append("\n");
} else { } else {
params0.append(comment).append("|").append(strRequired) commonHandleParam(paramList, param, isRequired, NO_COMMENTS_FOUND, since, strRequired);
.append("|").append(since).append("\n");
} }
} else { } else {
if (StringUtil.isEmpty(isRequired)) { ApiParam param = ApiParam.of().setField(pre + fieldName);
params0.append(NO_COMMENTS_FOUND).append("|").append(since).append("\n"); String processedType = DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase());
} else { param.setType(processedType);
params0.append(NO_COMMENTS_FOUND).append("|").append(strRequired) // params0.append(pre);
.append("|").append(since).append("\n"); // params0.append(fieldName).append("|")
} // .append(DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase())).append("|");
}
} else {
params0.append(pre);
params0.append(fieldName).append("|")
.append(DocClassUtil.processTypeNameForParams(typeSimpleName.toLowerCase())).append("|");
if (StringUtil.isNotEmpty(comment)) { if (StringUtil.isNotEmpty(comment)) {
if (StringUtil.isEmpty(isRequired)) { commonHandleParam(paramList, param, isRequired, comment, since, strRequired);
params0.append(comment).append("|").append(since).append("\n");
} else { } else {
params0.append(comment).append("|").append(strRequired) commonHandleParam(paramList, param, isRequired, NO_COMMENTS_FOUND, since, strRequired);
.append("|").append(since).append("\n");
}
} else {
if (StringUtil.isEmpty(isRequired)) {
params0.append(NO_COMMENTS_FOUND).append("|").append(since).append("\n");
} else {
params0.append("No comments found|").append(strRequired)
.append("|").append(since).append("\n");
}
} }
StringBuilder preBuilder = new StringBuilder(); StringBuilder preBuilder = new StringBuilder();
for (int j = 0; j < i; j++) { for (int j = 0; j < i; j++) {
@ -501,7 +501,10 @@ public class SourceBuilder {
if (DocClassUtil.isMap(subTypeName)) { if (DocClassUtil.isMap(subTypeName)) {
String gNameTemp = field.getType().getGenericCanonicalName(); String gNameTemp = field.getType().getGenericCanonicalName();
if (DocGlobalConstants.JAVA_MAP_FULLY.equals(gNameTemp)) { if (DocGlobalConstants.JAVA_MAP_FULLY.equals(gNameTemp)) {
params0.append(preBuilder + "any object|object|any object|-\n"); ApiParam param1 = ApiParam.of().setField(preBuilder.toString() + "any objec")
.setType("object").setDesc("any object").setVersion("-");
paramList.add(param1);
//params0.append(preBuilder + "any object|object|any object|-\n");
continue; continue;
} }
String valType = DocClassUtil.getMapKeyValueType(gNameTemp)[1]; String valType = DocClassUtil.getMapKeyValueType(gNameTemp)[1];
@ -509,10 +512,12 @@ public class SourceBuilder {
if (valType.length() == 1) { if (valType.length() == 1) {
String gicName = (n < globGicName.length) ? globGicName[n] : globGicName[globGicName.length - 1]; String gicName = (n < globGicName.length) ? globGicName[n] : globGicName[globGicName.length - 1];
if (!DocClassUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) { if (!DocClassUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) {
params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else { } else {
params0.append(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} }
} else if (DocClassUtil.isCollection(subTypeName)) { } else if (DocClassUtil.isCollection(subTypeName)) {
@ -529,11 +534,13 @@ public class SourceBuilder {
if (len > 0) { if (len > 0) {
String gicName = (n < len) ? globGicName[n] : globGicName[len - 1]; String gicName = (n < len) ? globGicName[n] : globGicName[len - 1];
if (!DocClassUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) { if (!DocClassUtil.isPrimitive(gicName) && !simpleName.equals(gicName)) {
params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} }
} else { } else {
params0.append(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} }
} }
@ -548,21 +555,27 @@ public class SourceBuilder {
if (DocClassUtil.isCollection(simple)) { if (DocClassUtil.isCollection(simple)) {
String gName = DocClassUtil.getSimpleGicName(gicName)[0]; String gName = DocClassUtil.getSimpleGicName(gicName)[0];
if (!DocClassUtil.isPrimitive(gName)) { if (!DocClassUtil.isPrimitive(gName)) {
params0.append(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else if (DocClassUtil.isMap(simple)) { } else if (DocClassUtil.isMap(simple)) {
String valType = DocClassUtil.getMapKeyValueType(gicName)[1]; String valType = DocClassUtil.getMapKeyValueType(gicName)[1];
if (!DocClassUtil.isPrimitive(valType)) { if (!DocClassUtil.isPrimitive(valType)) {
params0.append(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(valType, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else { } else {
params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else { } else {
params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(gicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else { } else {
params0.append(buildParams(subTypeName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(subTypeName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(subTypeName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} }
n++; n++;
@ -571,30 +584,34 @@ public class SourceBuilder {
if (className.equals(fieldGicName)) { if (className.equals(fieldGicName)) {
//do nothing //do nothing
} else if (!DocClassUtil.isPrimitive(fieldGicName)) { } else if (!DocClassUtil.isPrimitive(fieldGicName)) {
params0.append(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} else if (simpleName.equals(subTypeName)) { } else if (simpleName.equals(subTypeName)) {
//do nothing //do nothing
} else { } else {
params0.append(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp)); paramList.addAll(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
// params0.append(buildParams(fieldGicName, preBuilder.toString(), i + 1, isRequired, responseFieldMap, isResp));
} }
} }
} }
} }
} }
return params0.toString(); return paramList;
} }
private String primitiveReturnRespComment(String typeName) { private List<ApiParam> primitiveReturnRespComment(String typeName) {
StringBuilder comments = new StringBuilder(); StringBuilder comments = new StringBuilder();
comments.append("no param name|") comments.append("The api directly returns the ")
.append(typeName).append("|") .append(typeName).append(" type value.");
.append("The api directly returns the ") ApiParam apiParam = ApiParam.of().setField("no param name")
.append(typeName).append(" type value.").append("|-\n"); .setType(typeName).setDesc(comments.toString()).setVersion("-");
return comments.toString(); List<ApiParam> paramList = new ArrayList<>();
paramList.add(apiParam);
return paramList;
} }
/** /**
@ -918,7 +935,7 @@ public class SourceBuilder {
* @param className The class name * @param className The class name
* @return String * @return String
*/ */
private String getCommentTag(final JavaMethod javaMethod, final String tagName, final String className) { private List<ApiParam> getCommentTag(final JavaMethod javaMethod, final String tagName, final String className) {
// //
Map<String, CustomRespField> responseFieldMap = new HashMap<>(); Map<String, CustomRespField> responseFieldMap = new HashMap<>();
List<DocletTag> paramTags = javaMethod.getTagsByName(tagName); List<DocletTag> paramTags = javaMethod.getTagsByName(tagName);
@ -946,8 +963,10 @@ public class SourceBuilder {
List<JavaParameter> parameterList = javaMethod.getParameters(); List<JavaParameter> parameterList = javaMethod.getParameters();
if (parameterList.size() > 0) { if (parameterList.size() > 0) {
StringBuilder params = new StringBuilder(); StringBuilder params = new StringBuilder();
List<ApiParam> paramList = new ArrayList<>();
int requestBodyCounter = 0; int requestBodyCounter = 0;
StringBuilder reqBodyParams = new StringBuilder(); StringBuilder reqBodyParams = new StringBuilder();
List<ApiParam> reqBodyParamsList = new ArrayList<>();
StringBuilder reqParam = new StringBuilder(); StringBuilder reqParam = new StringBuilder();
out: out:
for (JavaParameter parameter : parameterList) { for (JavaParameter parameter : parameterList) {
@ -976,27 +995,44 @@ public class SourceBuilder {
String typeTemp = ""; String typeTemp = "";
if (DocClassUtil.isPrimitive(gicName)) { if (DocClassUtil.isPrimitive(gicName)) {
typeTemp = " of " + DocClassUtil.processTypeNameForParams(gicName); typeTemp = " of " + DocClassUtil.processTypeNameForParams(gicName);
reqParam.append(paramName).append("|") ApiParam param = ApiParam.of().setField(paramName)
.append(DocClassUtil.processTypeNameForParams(simpleName)).append(typeTemp).append("|") .setType(DocClassUtil.processTypeNameForParams(simpleName) + typeTemp)
.append(comment).append("|true|-\n"); .setDesc(comment).setRequired(true).setVersion("-");
paramList.add(param);
// reqParam.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append(typeTemp).append("|")
// .append(comment).append("|true|-\n");
} else { } else {
reqParam.append(paramName).append("|") ApiParam param = ApiParam.of().setField(paramName)
.append(DocClassUtil.processTypeNameForParams(simpleName)).append(typeTemp).append("|") .setType(DocClassUtil.processTypeNameForParams(simpleName) + typeTemp)
.append(comment).append("|true\n"); .setDesc(comment).setRequired(true).setVersion("-");
String strPrams = buildParams(gicNameArr[0], "└─", 1, "true", responseFieldMap, false); paramList.add(param);
reqParam.append(strPrams); // reqParam.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append(typeTemp).append("|")
// .append(comment).append("|true\n");
paramList.addAll(buildParams(gicNameArr[0], "└─", 1, "true", responseFieldMap, false));
// String strPrams = buildParams(gicNameArr[0], "└─", 1, "true", responseFieldMap, false);
// reqParam.append(strPrams);
} }
} else if (DocClassUtil.isPrimitive(simpleName)) { } else if (DocClassUtil.isPrimitive(simpleName)) {
reqParam.append(paramName).append("|") ApiParam param = ApiParam.of().setField(paramName)
.append(DocClassUtil.processTypeNameForParams(simpleName)).append("|") .setType(DocClassUtil.processTypeNameForParams(simpleName))
.append(comment).append("|true|-\n"); .setDesc(comment).setRequired(true).setVersion("-");
paramList.add(param);
// reqParam.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append("|")
// .append(comment).append("|true|-\n");
} else if (DocGlobalConstants.JAVA_MAP_FULLY.equals(typeName)) { } else if (DocGlobalConstants.JAVA_MAP_FULLY.equals(typeName)) {
reqParam.append(paramName).append("|") ApiParam param = ApiParam.of().setField(paramName)
.append("map").append("|") .setType("map").setDesc(comment).setRequired(true).setVersion("-");
.append(comment).append("|true|-\n"); paramList.add(param);
// reqParam.append(paramName).append("|")
// .append("map").append("|")
// .append(comment).append("|true|-\n");
} else { } else {
reqParam.append(buildParams(fullTypeName, "", 0, "true", responseFieldMap, false)); paramList.addAll(buildParams(fullTypeName, "", 0, "true", responseFieldMap, false));
//reqParam.append(buildParams(fullTypeName, "", 0, "true", responseFieldMap, false));
} }
} }
@ -1012,9 +1048,13 @@ public class SourceBuilder {
+ javaMethod.getName() + " in " + className + ",@RequestBody annotation could only bind one variables."); + javaMethod.getName() + " in " + className + ",@RequestBody annotation could only bind one variables.");
} }
if (DocClassUtil.isPrimitive(fullTypeName)) { if (DocClassUtil.isPrimitive(fullTypeName)) {
reqBodyParams.append(paramName).append("|") ApiParam bodyParam = ApiParam.of()
.append(DocClassUtil.processTypeNameForParams(simpleName)).append("|") .setField(paramName).setType(DocClassUtil.processTypeNameForParams(simpleName))
.append(comment).append("|").append(required).append("\n"); .setDesc(comment).setRequired(Boolean.valueOf(required));
reqBodyParams.append(bodyParam);
// reqBodyParams.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append("|")
// .append(comment).append("|").append(required).append("\n");
} else { } else {
if (DocClassUtil.isCollection(fullTypeName) || DocClassUtil.isArray(fullTypeName)) { if (DocClassUtil.isCollection(fullTypeName) || DocClassUtil.isArray(fullTypeName)) {
String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName);
@ -1023,45 +1063,61 @@ public class SourceBuilder {
gicName = gicName.substring(0, gicName.indexOf("[")); gicName = gicName.substring(0, gicName.indexOf("["));
} }
if (DocClassUtil.isPrimitive(gicName)) { if (DocClassUtil.isPrimitive(gicName)) {
reqBodyParams.append(paramName).append("|") ApiParam bodyParam = ApiParam.of()
.append(DocClassUtil.processTypeNameForParams(simpleName)).append("|") .setField(paramName).setType(DocClassUtil.processTypeNameForParams(simpleName))
.append(comment).append("|").append(required).append("\n"); .setDesc(comment).setRequired(Boolean.valueOf(required));
reqBodyParamsList.add(bodyParam);
// reqBodyParams.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append("|")
// .append(comment).append("|").append(required).append("\n");
} else { } else {
String strPrams = buildParams(gicNameArr[0], "", 0, "true", responseFieldMap, false); // String strPrams = buildParams(gicNameArr[0], "", 0, "true", responseFieldMap, false);
reqBodyParams.append(strPrams); reqBodyParamsList.addAll(buildParams(gicNameArr[0], "", 0, "true", responseFieldMap, false));
//reqBodyParams.append(strPrams);
} }
} else if (DocClassUtil.isMap(fullTypeName)) { } else if (DocClassUtil.isMap(fullTypeName)) {
if (DocGlobalConstants.JAVA_MAP_FULLY.equals(typeName)) { if (DocGlobalConstants.JAVA_MAP_FULLY.equals(typeName)) {
reqParam.append(paramName).append("|") ApiParam apiParam = ApiParam.of().setField(paramName).setType("map")
.append("map").append("|") .setDesc(comment).setRequired(Boolean.valueOf(required));
.append(comment).append("|").append(required).append("\n"); paramList.add(apiParam);
// reqParam.append(paramName).append("|")
// .append("map").append("|")
// .append(comment).append("|").append(required).append("\n");
continue out; continue out;
} }
String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName);
String strPrams = buildParams(gicNameArr[1], "", 0, "true", responseFieldMap, false); // String strPrams = buildParams(gicNameArr[1], "", 0, "true", responseFieldMap, false);
reqBodyParams.append(strPrams); // reqBodyParams.append(strPrams);
reqBodyParamsList.addAll(buildParams(gicNameArr[1], "", 0, "true", responseFieldMap, false));
} else { } else {
reqBodyParams.append(buildParams(typeName, "", 0, "true", responseFieldMap, false)); reqBodyParamsList.addAll(buildParams(typeName, "", 0, "true", responseFieldMap, false));
// reqBodyParams.append(buildParams(typeName, "", 0, "true", responseFieldMap, false));
} }
} }
requestBodyCounter++; requestBodyCounter++;
} else { } else {
reqParam.append(paramName).append("|") ApiParam param = ApiParam.of().setField(paramName)
.append(DocClassUtil.processTypeNameForParams(simpleName)).append("|") .setType(DocClassUtil.processTypeNameForParams(simpleName))
.append(comment).append("|") .setDesc(comment).setRequired(true).setVersion("-");
.append(required).append("|-\n"); paramList.add(param);
// reqParam.append(paramName).append("|")
// .append(DocClassUtil.processTypeNameForParams(simpleName)).append("|")
// .append(comment).append("|")
// .append(required).append("|-\n");
} }
} }
} }
} }
if (requestBodyCounter > 0) { if (requestBodyCounter > 0) {
params.append(reqBodyParams); paramList.addAll(reqBodyParamsList);
return params.toString(); // params.append(reqBodyParams);
return paramList;
} }
params.append(reqParam); //params.append(reqParam);
return params.toString(); return paramList;
} }
return null; return null;
} }
@ -1142,4 +1198,17 @@ public class SourceBuilder {
} }
} }
} }
private void commonHandleParam(List<ApiParam> paramList, ApiParam param, String isRequired, String comment, String since, boolean strRequired) {
if (StringUtil.isEmpty(isRequired)) {
param.setDesc(comment).setVersion(since);
paramList.add(param);
// params0.append(NO_COMMENTS_FOUND).append("|").append(since).append("\n");
} else {
param.setDesc(comment).setVersion(since).setRequired(strRequired);
paramList.add(param);
// params0.append("No comments found|").append(strRequired)
// .append("|").append(since).append("\n");
}
}
} }

1
src/main/java/com/power/doc/constants/DocAnnotationConstants.java
View File

@ -2,6 +2,7 @@ package com.power.doc.constants;
/** /**
* java annotations * java annotations
*
* @author yu 2019/9/19. * @author yu 2019/9/19.
*/ */
public class DocAnnotationConstants { public class DocAnnotationConstants {

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

@ -66,5 +66,4 @@ public class DocGlobalConstants {
public static final String JAVA_LIST_FULLY = "java.util.List"; public static final String JAVA_LIST_FULLY = "java.util.List";
} }

2
src/main/java/com/power/doc/constants/DocLanguage.java
View File

@ -1,8 +1,8 @@
package com.power.doc.constants; package com.power.doc.constants;
/** /**
*
* language support * language support
*
* @author yu 2019/9/21. * @author yu 2019/9/21.
*/ */
public enum DocLanguage { public enum DocLanguage {

1
src/main/java/com/power/doc/constants/TemplateVariable.java
View File

@ -18,7 +18,6 @@ public enum TemplateVariable {
VERSION("version"); VERSION("version");
private String variable; private String variable;
TemplateVariable(String variable) { TemplateVariable(String variable) {

14
src/main/java/com/power/doc/model/ApiConfig.java
View File

@ -74,10 +74,16 @@ public class ApiConfig {
/** /**
* language support * language support
*
* @since 1.7+ * @since 1.7+
*/ */
private DocLanguage language; private DocLanguage language;
/**
* adoc flag
*/
private boolean adoc;
public String getServerUrl() { public String getServerUrl() {
return serverUrl; return serverUrl;
@ -176,5 +182,11 @@ public class ApiConfig {
this.language = language; this.language = language;
} }
public boolean isAdoc() {
return adoc;
}
public void setAdoc(boolean adoc) {
this.adoc = adoc;
}
} }

52
src/main/java/com/power/doc/model/ApiMethodDoc.java
View File

@ -1,6 +1,7 @@
package com.power.doc.model; package com.power.doc.model;
import java.io.Serializable; import java.io.Serializable;
import java.util.List;
/** /**
* java api method info model. * java api method info model.
@ -31,6 +32,7 @@ public class ApiMethodDoc implements Serializable {
private String type; private String type;
/** /**
* only used for generate markdown and adoc
* http readers * http readers
*/ */
private String headers; private String headers;
@ -40,10 +42,16 @@ public class ApiMethodDoc implements Serializable {
*/ */
private String contentType = "application/x-www-form-urlencoded"; private String contentType = "application/x-www-form-urlencoded";
/**
* http request headers
*/
private List<ApiReqHeader> requestHeaders;
/** /**
* http request params * http request params
*/ */
private String requestParams; private List<ApiParam> requestParams;
/** /**
* http request usage * http request usage
@ -58,7 +66,7 @@ public class ApiMethodDoc implements Serializable {
/** /**
* http response params * http response params
*/ */
private String responseParams; private List<ApiParam> responseParams;
public String getDesc() { public String getDesc() {
@ -85,14 +93,6 @@ public class ApiMethodDoc implements Serializable {
this.type = type; this.type = type;
} }
public String getRequestParams() {
return requestParams;
}
public void setRequestParams(String requestParams) {
this.requestParams = requestParams;
}
public String getResponseUsage() { public String getResponseUsage() {
return responseUsage; return responseUsage;
} }
@ -101,14 +101,6 @@ public class ApiMethodDoc implements Serializable {
this.responseUsage = responseUsage; this.responseUsage = responseUsage;
} }
public String getResponseParams() {
return responseParams;
}
public void setResponseParams(String responseParams) {
this.responseParams = responseParams;
}
public String getRequestUsage() { public String getRequestUsage() {
return requestUsage; return requestUsage;
} }
@ -140,4 +132,28 @@ public class ApiMethodDoc implements Serializable {
public void setOrder(int order) { public void setOrder(int order) {
this.order = order; this.order = order;
} }
public List<ApiParam> getRequestParams() {
return requestParams;
}
public void setRequestParams(List<ApiParam> requestParams) {
this.requestParams = requestParams;
}
public List<ApiParam> getResponseParams() {
return responseParams;
}
public void setResponseParams(List<ApiParam> responseParams) {
this.responseParams = responseParams;
}
public List<ApiReqHeader> getRequestHeaders() {
return requestHeaders;
}
public void setRequestHeaders(List<ApiReqHeader> requestHeaders) {
this.requestHeaders = requestHeaders;
}
} }

39
src/main/java/com/power/doc/model/ApiParam.java Normal file
View File

@ -0,0 +1,39 @@
package com.power.doc.model;
import lombok.Data;
import lombok.RequiredArgsConstructor;
import lombok.experimental.Accessors;
/**
* @author yu 2019/9/27.
*/
@Data
@Accessors(chain = true)
@RequiredArgsConstructor(staticName = "of")
public class ApiParam {
/**
* field
*/
private String field;
/**
* field type
*/
private String type;
/**
* description
*/
private String desc;
/**
* require flag
*/
private boolean required;
/**
* version
*/
private String version;
}

2
src/main/java/com/power/doc/model/ApiReturn.java
View File

@ -1,8 +1,8 @@
package com.power.doc.model; package com.power.doc.model;
/** /**
* @since 1.7 +
* @author yu 2019/9/22. * @author yu 2019/9/22.
* @since 1.7 +
*/ */
public class ApiReturn { public class ApiReturn {

1
src/main/java/com/power/doc/model/CustomRespField.java
View File

@ -4,6 +4,7 @@ package com.power.doc.model;
* Description: * Description:
* This can be used to customize the comments for setting java fields. * This can be used to customize the comments for setting java fields.
* You can reference README.md * You can reference README.md
*
* @author yu 2018/06/18. * @author yu 2018/06/18.
*/ */
public class CustomRespField { public class CustomRespField {

1
src/main/java/com/power/doc/model/SourceCodePath.java
View File

@ -2,6 +2,7 @@ package com.power.doc.model;
/** /**
* Source code path * Source code path
*
* @author yu 2018/7/14. * @author yu 2018/7/14.
*/ */
public class SourceCodePath { public class SourceCodePath {

2
src/main/java/com/power/doc/utils/BeetlTemplateUtil.java
View File

@ -21,6 +21,7 @@ public class BeetlTemplateUtil {
/** /**
* Get Beetl template by file name * Get Beetl template by file name
*
* @param templateName template name * @param templateName template name
* @return Beetl Template Object * @return Beetl Template Object
*/ */
@ -38,6 +39,7 @@ public class BeetlTemplateUtil {
/** /**
* Batch bind binding value to Beetl templates and return all file rendered, * Batch bind binding value to Beetl templates and return all file rendered,
* Map key is file name,value is file content * Map key is file name,value is file content
*
* @param path path * @param path path
* @param params params * @param params params
* @return map * @return map

2
src/main/java/com/power/doc/utils/DocUtil.java
View File

@ -221,6 +221,7 @@ public class DocUtil {
/** /**
* handle spring mvc method * handle spring mvc method
*
* @param method method name * @param method method name
* @return String * @return String
*/ */
@ -241,6 +242,7 @@ public class DocUtil {
/** /**
* handle spring mvc mapping value * handle spring mvc mapping value
*
* @param annotation JavaAnnotation * @param annotation JavaAnnotation
* @return String * @return String
*/ */

2
src/main/java/com/power/doc/utils/MarkDownUtil.java
View File

@ -10,8 +10,8 @@ import com.vladsch.flexmark.util.data.MutableDataSet;
import java.util.Arrays; import java.util.Arrays;
/** /**
* @since 1.7+
* @author yu 2019/9/21. * @author yu 2019/9/21.
* @since 1.7+
*/ */
public class MarkDownUtil { public class MarkDownUtil {

12
src/main/resources/template/AllInOne.adoc
View File

@ -45,7 +45,11 @@ ${doc.headers}
[stripes=even] [stripes=even]
|==================== |====================
|Parameter | Type|Description|Required|Since |Parameter | Type|Description|Required|Since
${doc.requestParams} <%
for(param in doc.requestParams){
%>
|{param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
<%}%>
|==================== |====================
<%}%> <%}%>
@ -62,7 +66,11 @@ ${doc.requestUsage}
[stripes=even] [stripes=even]
|==================== |====================
|Field | Type|Description|Since |Field | Type|Description|Since
${doc.responseParams} <%
for(param in doc.responseParams){
%>
|${param.field}|${param.type}|${param.desc}|${param.version}
<%}%>
|==================== |====================
<%}%> <%}%>

12
src/main/resources/template/ApiDoc.adoc
View File

@ -28,7 +28,11 @@ ${doc.headers}
[stripes=even] [stripes=even]
|==================== |====================
|Parameter | Type|Description|Required|Since |Parameter | Type|Description|Required|Since
${doc.requestParams} <%
for(param in doc.requestParams){
%>
|{param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
<%}%>
<%}%> <%}%>
|==================== |====================
@ -45,7 +49,11 @@ ${doc.requestUsage}
[stripes=even] [stripes=even]
|==================== |====================
|Field | Type|Description|Since |Field | Type|Description|Since
${doc.responseParams} <%
for(param in doc.responseParams){
%>
|${param.field}|${param.type}|${param.desc}|${param.version}
<%}%>
<%}%> <%}%>
|==================== |====================