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

24
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
*
* @author yu 2019/9/26.
*/
public class AdocDocBuilder {
@ -17,19 +18,34 @@ public class AdocDocBuilder {
private static final String INDEX_DOC = "index.adoc";
/** build adoc
/**
* build adoc
*
* @param config ApiConfig
*/
public static void builderControllersApi(ApiConfig config) {
config.setAdoc(true);
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
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);
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);
builderTemplate.buildApiDoc(apiDocList, config, API_DOC_ADOC_TPL, API_EXTENSION);
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);
}
}

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

@ -23,18 +23,55 @@ public class ApiDocBuilder {
* @param config ApiConfig
*/
public static void builderControllersApi(ApiConfig config) {
config.setAdoc(false);
DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
builderTemplate.checkAndInit(config);
SourceBuilder sourceBuilder = new SourceBuilder(config);
List<ApiDoc> apiDocList = sourceBuilder.getControllerApiData();
if (config.isAllInOne()) {
String version = DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT);
builderTemplate.buildAllInOne(apiDocList,config,ALL_IN_ONE_MD_TPL,"AllInOne-V" + version + ".md");
builderTemplate.buildAllInOne(apiDocList, config, ALL_IN_ONE_MD_TPL, "AllInOne-V" + version + ".md");
} else {
builderTemplate.buildApiDoc(apiDocList,config,API_DOC_MD_TPL,API_EXTENSION);
builderTemplate.buildErrorCodeDoc(config.getErrorCodes(),config,ERROR_CODE_LIST_MD_TPL,ERROR_CODE_LIST_MD);
builderTemplate.buildApiDoc(apiDocList, config, API_DOC_MD_TPL, API_EXTENSION);
builderTemplate.buildErrorCodeDoc(config.getErrorCodes(), config, ERROR_CODE_LIST_MD_TPL, ERROR_CODE_LIST_MD);
}
}
/**
* Generate a single controller api document
*
* @param 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);
}
}

50
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.
*
@ -69,9 +86,10 @@ public class DocBuilderTemplate {
/**
* Merge all api doc into one document
* @param apiDocList list data of Api doc
* @param config api config
* @param template template
*
* @param apiDocList list data of Api doc
* @param config api config
* @param template template
* @param outPutFileName output file
*/
public void buildAllInOne(List<ApiDoc> apiDocList, ApiConfig config, String template, String outPutFileName) {
@ -87,9 +105,10 @@ public class DocBuilderTemplate {
/**
* build error_code adoc
* @param errorCodeList list data of Api doc
* @param config api config
* @param template template
*
* @param errorCodeList list data of Api doc
* @param config api config
* @param template template
* @param outPutFileName output file
*/
public void buildErrorCodeDoc(List<ApiErrorCode> errorCodeList, ApiConfig config, String template, String outPutFileName) {
@ -99,4 +118,23 @@ public class DocBuilderTemplate {
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);
}
}

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

@ -28,6 +28,7 @@ public class HtmlApiDocBuilder {
/**
* build controller api
*
* @param config config
*/
public static void builderControllersApi(ApiConfig config) {
@ -60,8 +61,9 @@ public class HtmlApiDocBuilder {
/**
* build api.html
*
* @param apiDocList list of api doc
* @param config ApiConfig
* @param config ApiConfig
*/
private static void buildIndex(List<ApiDoc> apiDocList, ApiConfig config) {
FileUtil.mkdirs(config.getOutPath());
@ -88,7 +90,7 @@ public class HtmlApiDocBuilder {
* build ever controller api
*
* @param apiDocList list of api doc
* @param outPath output path
* @param outPath output path
*/
private static void buildApiDoc(List<ApiDoc> apiDocList, String outPath) {
FileUtil.mkdirs(outPath);

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

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

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

@ -2,6 +2,7 @@ package com.power.doc.constants;
/**
* java annotations
*
* @author yu 2019/9/19.
*/
public class DocAnnotationConstants {
@ -10,7 +11,7 @@ public class DocAnnotationConstants {
public static final String SHORT_REST_CONTROLLER = "RestController";
public static final String SHORT_JSON_IGNORE= "JsonIgnore";
public static final String SHORT_JSON_IGNORE = "JsonIgnore";
public static final String SHORT_JSON_PROPERTY = "JsonProperty";

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";
}

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

@ -1,8 +1,8 @@
package com.power.doc.constants;
/**
*
* language support
*
* @author yu 2019/9/21.
*/
public enum DocLanguage {
@ -15,7 +15,7 @@ public enum DocLanguage {
this.code = code;
}
public String getCode(){
public String getCode() {
return this.code;
}
}

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

@ -3,7 +3,7 @@ package com.power.doc.constants;
/**
* @author yu 2019/9/21.
*/
public enum TemplateVariable {
public enum TemplateVariable {
DESC("desc"),
NAME("name"),
LIST("list"),
@ -18,14 +18,13 @@ public enum TemplateVariable {
VERSION("version");
private String variable;
TemplateVariable(String variable) {
this.variable = variable;
}
public String getVariable(){
public String getVariable() {
return this.variable;
}
}

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

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

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

@ -22,7 +22,7 @@ public class ApiDoc {
private String alias;
/**
* List of method doc
* List of method doc
*/
private List<ApiMethodDoc> list;

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

@ -1,6 +1,7 @@
package com.power.doc.model;
import java.io.Serializable;
import java.util.List;
/**
* java api method info model.
@ -31,6 +32,7 @@ public class ApiMethodDoc implements Serializable {
private String type;
/**
* only used for generate markdown and adoc
* http readers
*/
private String headers;
@ -40,10 +42,16 @@ public class ApiMethodDoc implements Serializable {
*/
private String contentType = "application/x-www-form-urlencoded";
/**
* http request headers
*/
private List<ApiReqHeader> requestHeaders;
/**
* http request params
*/
private String requestParams;
private List<ApiParam> requestParams;
/**
* http request usage
@ -58,7 +66,7 @@ public class ApiMethodDoc implements Serializable {
/**
* http response params
*/
private String responseParams;
private List<ApiParam> responseParams;
public String getDesc() {
@ -85,14 +93,6 @@ public class ApiMethodDoc implements Serializable {
this.type = type;
}
public String getRequestParams() {
return requestParams;
}
public void setRequestParams(String requestParams) {
this.requestParams = requestParams;
}
public String getResponseUsage() {
return responseUsage;
}
@ -101,14 +101,6 @@ public class ApiMethodDoc implements Serializable {
this.responseUsage = responseUsage;
}
public String getResponseParams() {
return responseParams;
}
public void setResponseParams(String responseParams) {
this.responseParams = responseParams;
}
public String getRequestUsage() {
return requestUsage;
}
@ -140,4 +132,28 @@ public class ApiMethodDoc implements Serializable {
public void setOrder(int 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;
/**
* @since 1.7 +
* @author yu 2019/9/22.
* @since 1.7 +
*/
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:
* This can be used to customize the comments for setting java fields.
* You can reference README.md
*
* @author yu 2018/06/18.
*/
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
*
* @author yu 2018/7/14.
*/
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
*
* @param templateName template name
* @return Beetl Template Object
*/
@ -38,6 +39,7 @@ public class BeetlTemplateUtil {
/**
* Batch bind binding value to Beetl templates and return all file rendered,
* Map key is file name,value is file content
*
* @param path path
* @param params params
* @return map

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

@ -102,7 +102,7 @@ public class DocUtil {
/**
* Generate random field values based on field field names and type.
*
* @param typeName field type name
* @param typeName field type name
* @param filedName field name
* @return random value
*/
@ -221,6 +221,7 @@ public class DocUtil {
/**
* handle spring mvc method
*
* @param method method name
* @return String
*/
@ -234,19 +235,20 @@ public class DocUtil {
return "PUT";
case "RequestMethod.DELETE":
return "DELETE";
default:
return "GET";
default:
return "GET";
}
}
/**
* handle spring mvc mapping value
*
* @param annotation JavaAnnotation
* @return String
*/
public static String handleMappingValue(JavaAnnotation annotation){
public static String handleMappingValue(JavaAnnotation annotation) {
if (null == annotation.getNamedParameter("value")) {
return "/";
return "/";
} else {
return annotation.getNamedParameter("value").toString();
}

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;
/**
* @since 1.7+
* @author yu 2019/9/21.
* @since 1.7+
*/
public class MarkDownUtil {

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

@ -45,7 +45,11 @@ ${doc.headers}
[stripes=even]
|====================
|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]
|====================
|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]
|====================
|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]
|====================
|Field | Type|Description|Since
${doc.responseParams}
<%
for(param in doc.responseParams){
%>
|${param.field}|${param.type}|${param.desc}|${param.version}
<%}%>
<%}%>
|====================