diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 830afe8..da09d08 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,43 +1,37 @@ --- -name: Bug report 🐞 about: Create a report to help us improve title: '' -labels: bug assignees: '' +name: Bug report 🐞 +about: Create a report to help us improve +title: '' +labels: bug +assignees: '' --- - ## Your Environment(您的使用环境) - - * smart-doc version: * plugin version (e.g. smart-doc-maven-plugin or smart-doc-gradle-plugin): * build tool version(maven or gradle): ## Expected Behavior(您期望的结果) - ## Current Behavior(当前结果) - ## Possible Solution(bug解决建议) - ## Steps to Reproduce (Bug产生步骤,请尽量提供用例代码) - - 1. 2. 3. 4. ## Context(Bug影响描述) - diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bfffa7e..1045ec4 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,5 +1,7 @@ --- -name: Feature Request 💡 about: Suggest a new idea for the project. labels: enhancement +name: Feature Request 💡 +about: Suggest a new idea for the project. +labels: enhancement --- ## Summary(关于这个pr的描述) diff --git a/CHANGELOG.md b/CHANGELOG.md index 58264bc..c106673 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,19 @@ #### 版本号:2.2.3 -- 更新日期: 2020-07-12 +- 更新日期: 2021-07-18 - 更新内容: 1. 增加pathPrefix配置项用于配置上下文,引入该配置项后serverUrl仅用于配置服务器地址。 2. 支持请求头常量设置解析。 3. 支持使用JsonIgnoreProperties和JSONType注解去忽略多字段。 + 4. 修改部分文档设置allInOneDocFileName无效的问题,#131 。 + 5. 修复dubbo rpc文档模板格式错误 #https://gitee.com/smart-doc-team/smart-doc/issues/I40ZGE . + 6. 支持配置添加拦截器中设置全局请求参数,#https://github.com/smart-doc-group/smart-doc/issues/132 . + 7. 修复部分类型mock未推送到torna的问题。 + #### 版本号:2.2.2 -- 更新日期: 2020-07-04 +- 更新日期: 2021-07-04 - 更新内容: 1. 修复url中遇到正则表达解析错误问题. 2. 修复生成的json样例部分格式化后错误的bug,gitee #I3XSE5。 @@ -27,13 +32,13 @@ 14. 修复高版本gradle中使用implements添加依赖时,gradle插件无法加载依赖导致返回空json的bug。 #### 版本号:2.2.1 -- 更新日期: 2020-06-20 +- 更新日期: 2021-06-20 - 更新内容: 1. 移除代码中System.out.print打印. #### 版本号:2.2.0 -- 更新日期: 2020-06-20 +- 更新日期: 2021-06-20 - 更新内容: 1. 修复参数多行注释时,注释提取错误,gitee #I3TYYP. 2. 修复部分代码可能出现的空指针问题。 @@ -44,7 +49,7 @@ 7. 移除YapiBuilder。smart-doc不在支持其他第三方接口系统,请使用torna. #### 版本号:2.1.9 -- 更新日期: 2020-05-29 +- 更新日期: 2021-05-29 - 更新内容: 1. 修复inlineEnum为false时枚举展示在参数中的问题。 2. 返回Spring文件下载对象支持自动识别为文件下载,减少手动标记@download tag。 @@ -56,7 +61,7 @@ 8. 优化字典码推送,空字典码不会像torna发起推送请求。 #### 版本号:2.1.8 -- 更新日期: 2020-05-22 +- 更新日期: 2021-05-22 - 更新内容: 1. 修复推送接口到torna丢失部分mock值的问题。 2. 修复在参数注释中配置类替换时将非类名解析成类名的bug 。 @@ -68,14 +73,14 @@ 8. 添加@JsonProperty支持,支持JsonProperty.Access控制字段。 #### 版本号:2.1.7 -- 更新日期: 2020-05-12 +- 更新日期: 2021-05-12 - 更新内容: 1. 添加推送接口作者信息到torna数据错误的bug。 2. 修复空参数curl命令多余?号问题,github 。 #### 版本号:2.1.6 -- 更新日期: 2020-05-10 +- 更新日期: 2021-05-10 - 更新内容: 1. 修复不允许List中放文件上传对象错误的bug。 2. 添加推送接口作者信息到torna,通过配置author设置推送人,不配置默认为计算机用户名。 @@ -83,14 +88,14 @@ #### 版本号:2.1.5 -- 更新日期: 2020-05-05 +- 更新日期: 2021-05-05 - 更新内容: 1. 修复requestBodyAdvice请求样例丢之。 2. 添加dubbo文档到torna的推送。 #### 版本号:2.1.4 -- 更新日期: 2020-04-24 +- 更新日期: 2021-04-24 - 更新内容: 1. 修复Controller继承时,父类的Mapping未继承的问题。 2. 修复配置responseBodyAdvice后,controller中void方法返回显示错误。 @@ -102,7 +107,7 @@ #### 版本号:2.1.3 -- 更新日期: 2020-04-11 +- 更新日期: 2021-04-11 - 更新内容: 1. 增强对文件上传的支持。 2. 增加customRequestFields配置项,#97。 @@ -112,21 +117,21 @@ #### 版本号:2.1.2 -- 更新日期: 2020-03-29 +- 更新日期: 2021-03-29 - 更新内容: 1. 修复Map嵌套在某些结构体中栈溢出问题,gitee #I3CCLY。 2. 修复Torna数据推送问题。 #### 版本号:2.1.1 -- 更新日期: 2020-03-24 +- 更新日期: 2021-03-24 - 更新内容: 1. 修复Map嵌套在某些结构体中栈溢出问题,gitee #I3CCLY。 2. 修复Torna数据推送问题。 #### 版本号:2.1.0 -- 更新日期: 2020-03-21 +- 更新日期: 2021-03-21 - 更新内容: 1. 导出的postman的url资源下添加缺失的protocol。 2. 增加@ignoreParams自定义tag来过滤掉不想显示在文档中参数。 @@ -136,7 +141,7 @@ #### 版本号:2.0.9 -- 更新日期: 2020-03-12 +- 更新日期: 2021-03-12 - 更新内容: 1. 支持UUID和ZonedDateTime字段类型,#89。 2. 对map参数增加开关来兼容旧项目,还是不建议使用map参数。 @@ -144,7 +149,7 @@ #### 版本号:2.0.8 -- 更新日期: 2020-02-26 +- 更新日期: 2021-02-26 - 更新内容: 1. 修复文件上传的参数丢失的注释。 2. 修复2.0.7新增忽略接口方法后解析父类字段缺失注释bug。 @@ -152,7 +157,7 @@ #### 版本号:2.0.7 -- 更新日期: 2020-01-30 +- 更新日期: 2021-01-30 - 更新内容: 1. 修复postman的url中不附加的context-path的问题。 2. 修复带正则的path路径参数解析出现截取越界的问题。 @@ -162,21 +167,21 @@ #### 版本号:2.0.6 -- 更新日期: 2020-01-15 +- 更新日期: 2021-01-15 - 更新内容: 1. 修复带正则的path路径参数在postman中用例问题。 2. 增强对祖传不良代码的分析兼容。 #### 版本号:2.0.5 -- 更新日期: 2020-01-09 +- 更新日期: 2021-01-09 - 更新内容: 1. 修复集合类无泛型参数作为入参出参时的数组越界。 2. 修复新开tab访问的url拼接问题。 #### 版本号:2.0.3-2.0.4 -- 更新日期: 2020-01-01 +- 更新日期: 2021-01-01 - 更新内容: 1. 修改页面的错误列表标题显示。 2. 修改debug页面curl header语法错误。 @@ -185,7 +190,7 @@ #### 版本号:2.0.2 -- 更新日期: 2020-02-27 +- 更新日期: 2020-12-27 - 更新内容: 1. 修改创建openapi时的空指针异常。 2. 修改debug页面时未使用mock值的问题。 diff --git a/README.md b/README.md index e4d6cbf..f8a39e5 100644 --- a/README.md +++ b/README.md @@ -201,8 +201,34 @@ When you need to use smart-doc to generate more API document information, you ca "type": "string", "desc": "desc", "required": false, + "pathPatterns": "*", + "excludePathPatterns":"/app/page/**" "since": "-" - }] + }], + "requestParams": [ //Public request parameters (a scenario where public request parameters are processed through interceptors) ,@since 2.2.3,no need to set + { + "name": "configPathParam", + "type": "string", + "desc": "desc", + "paramIn": "path", // path,query + "value":"testPath",//default is null + "required": false, + "since": "-", + "pathPatterns": "*", + "excludePathPatterns":"/app/page/**" + }, + { + "name": "configQueryParam", + "type": "string", + "desc": "desc", + "paramIn": "query", + "value":"testQuery", + "required": false, + "since": "-", + "pathPatterns": "*", + "excludePathPatterns":"/app/page/**" + } + ] } ``` diff --git a/README_CN.md b/README_CN.md index 60b3c0d..2a1f374 100644 --- a/README_CN.md +++ b/README_CN.md @@ -204,6 +204,30 @@ smart-doc官方目前已经开发完成[Maven插件](https://gitee.com/smart-doc "pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头,多个正则用分号隔开 "since": "-"//什么版本添加的改请求头 }], + "requestParams": [ //公共请求参数(通过拦截器处理的场景),@since 2.2.3,没有需求请不要设置 + { + "name": "configPathParam",//请求头名称 + "type": "string",//请求头类型 + "desc": "desc",//请求头描述信息 + "paramIn": "path", + "value":"testPath",//不设置默认null + "required": false,//是否必须 + "since": "-",//什么版本添加的改请求头 + "pathPatterns": "*",//正则表达式过滤请求头 + "excludePathPatterns":"/app/page/**" //参考请求头中的用法 + }, + { + "name": "configQueryParam",//请求头名称 + "type": "string",//请求头类型 + "desc": "desc",//请求头描述信息 + "paramIn": "query", + "value":"testQuery",//不设置默认null + "required": false,//是否必须 + "since": "-",//什么版本添加的改请求头 + "pathPatterns": "*",//正则表达式过滤请求头 + "excludePathPatterns":"/app/page/**" + } + ], "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖,配置后输出到文档方便使用者集成 "artifactId":"SpringBoot2-Dubbo-Api", "groupId":"com.demo", diff --git a/pom.xml b/pom.xml index 1995b4c..98868af 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 smart-doc jar - 2.2.2 + 2.2.3 smart-doc https://github.com/smart-doc-group/smart-doc.git diff --git a/src/main/java/com/power/doc/builder/AdocDocBuilder.java b/src/main/java/com/power/doc/builder/AdocDocBuilder.java index c3bdd3b..d7a8fc5 100644 --- a/src/main/java/com/power/doc/builder/AdocDocBuilder.java +++ b/src/main/java/com/power/doc/builder/AdocDocBuilder.java @@ -22,6 +22,7 @@ */ package com.power.doc.builder; +import com.power.common.util.DateTimeUtil; import com.power.doc.factory.BuildTemplateFactory; import com.power.doc.model.ApiConfig; import com.power.doc.model.ApiDoc; @@ -69,7 +70,8 @@ public class AdocDocBuilder { IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework()); List apiDocList = docBuildTemplate.getApiData(configBuilder); if (config.isAllInOne()) { - builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_ADOC_TPL, INDEX_DOC); + String docName = builderTemplate.allInOneDocName(config,INDEX_DOC,".doc"); + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_ADOC_TPL, docName); } else { builderTemplate.buildApiDoc(apiDocList, config, API_DOC_ADOC_TPL, API_EXTENSION); builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC); diff --git a/src/main/java/com/power/doc/builder/ApiDocBuilder.java b/src/main/java/com/power/doc/builder/ApiDocBuilder.java index 47005d9..c9b119f 100644 --- a/src/main/java/com/power/doc/builder/ApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/ApiDocBuilder.java @@ -69,7 +69,8 @@ public class ApiDocBuilder { List apiDocList = docBuildTemplate.getApiData(configBuilder); if (config.isAllInOne()) { String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT); - builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_MD_TPL, "AllInOne" + version + ".md"); + String docName = builderTemplate.allInOneDocName(config,"AllInOne" + version + ".md",".md"); + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_MD_TPL, docName); } else { builderTemplate.buildApiDoc(apiDocList, config, API_DOC_MD_TPL, API_EXTENSION); builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_MD_TPL, ERROR_CODE_LIST_MD); diff --git a/src/main/java/com/power/doc/builder/BaseDocBuilderTemplate.java b/src/main/java/com/power/doc/builder/BaseDocBuilderTemplate.java index 8d4ab08..20f82a7 100644 --- a/src/main/java/com/power/doc/builder/BaseDocBuilderTemplate.java +++ b/src/main/java/com/power/doc/builder/BaseDocBuilderTemplate.java @@ -30,6 +30,7 @@ import com.power.doc.constants.FrameworkEnum; import com.power.doc.constants.TemplateVariable; import com.power.doc.model.ApiConfig; import com.power.doc.model.RevisionLog; +import org.apache.commons.lang3.StringUtils; import org.beetl.core.Template; import java.util.HashMap; @@ -121,4 +122,19 @@ public class BaseDocBuilderTemplate { template.binding(TemplateVariable.CSS_CND.getVariable(), CSS_CDN); } } + + public String allInOneDocName(ApiConfig apiConfig, String fileName, String suffix) { + String allInOneName = apiConfig.getAllInOneDocFileName(); + if (StringUtils.isNotEmpty(apiConfig.getAllInOneDocFileName())) { + if (allInOneName.endsWith(suffix)) { + return allInOneName; + } else { + return allInOneName + suffix; + } + } else if (fileName.equals(suffix)) { + return fileName; + } else { + return fileName + suffix; + } + } } diff --git a/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java index 6245093..cf66340 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcAdocBuilder.java @@ -28,7 +28,6 @@ import com.power.doc.factory.BuildTemplateFactory; import com.power.doc.model.ApiConfig; import com.power.doc.model.rpc.RpcApiDoc; import com.power.doc.template.IDocBuildTemplate; -import com.power.doc.template.RpcDocBuildTemplate; import com.thoughtworks.qdox.JavaProjectBuilder; import java.util.List; @@ -70,7 +69,8 @@ public class RpcAdocBuilder { IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework()); List apiDocList = docBuildTemplate.getApiData(configBuilder); if (config.isAllInOne()) { - builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, RPC_ALL_IN_ONE_ADOC_TPL, INDEX_DOC); + String docName = builderTemplate.allInOneDocName(config, INDEX_DOC, ".adoc"); + builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, RPC_ALL_IN_ONE_ADOC_TPL, docName); } else { builderTemplate.buildApiDoc(apiDocList, config, RPC_API_DOC_ADOC_TPL, API_EXTENSION); builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_ADOC_TPL, ERROR_CODE_LIST_ADOC); diff --git a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java index 530a801..fd7356d 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcMarkdownBuilder.java @@ -28,7 +28,6 @@ import com.power.doc.factory.BuildTemplateFactory; import com.power.doc.model.ApiConfig; import com.power.doc.model.rpc.RpcApiDoc; import com.power.doc.template.IDocBuildTemplate; -import com.power.doc.template.RpcDocBuildTemplate; import com.thoughtworks.qdox.JavaProjectBuilder; import java.util.List; @@ -55,23 +54,24 @@ public class RpcMarkdownBuilder { /** * Only for smart-doc maven plugin and gradle plugin. * - * @param config ApiConfig + * @param apiConfig ApiConfig * @param javaProjectBuilder ProjectDocConfigBuilder */ - public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) { - config.setAdoc(false); - config.setShowJavaType(true); + public static void buildApiDoc(ApiConfig apiConfig, JavaProjectBuilder javaProjectBuilder) { + apiConfig.setAdoc(false); + apiConfig.setShowJavaType(true); RpcDocBuilderTemplate builderTemplate = new RpcDocBuilderTemplate(); - builderTemplate.checkAndInit(config); - ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder); - IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework()); + builderTemplate.checkAndInit(apiConfig); + ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(apiConfig, javaProjectBuilder); + IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(apiConfig.getFramework()); List apiDocList = docBuildTemplate.getApiData(configBuilder); - if (config.isAllInOne()) { - String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT); - builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, RPC_ALL_IN_ONE_MD_TPL, "rpc-all" + version + ".md"); + if (apiConfig.isAllInOne()) { + String version = apiConfig.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT); + String docName = builderTemplate.allInOneDocName(apiConfig, "rpc-all" + version, ".md"); + builderTemplate.buildAllInOne(apiDocList, apiConfig, javaProjectBuilder, RPC_ALL_IN_ONE_MD_TPL, docName); } else { - builderTemplate.buildApiDoc(apiDocList, config, RPC_API_DOC_MD_TPL, API_EXTENSION); - builderTemplate.buildErrorCodeDoc(config, ERROR_CODE_LIST_MD_TPL, ERROR_CODE_LIST_MD); + builderTemplate.buildApiDoc(apiDocList, apiConfig, RPC_API_DOC_MD_TPL, API_EXTENSION); + builderTemplate.buildErrorCodeDoc(apiConfig, ERROR_CODE_LIST_MD_TPL, ERROR_CODE_LIST_MD); } } } diff --git a/src/main/java/com/power/doc/helper/JsonBuildHelper.java b/src/main/java/com/power/doc/helper/JsonBuildHelper.java index a5e4fb6..cd88296 100644 --- a/src/main/java/com/power/doc/helper/JsonBuildHelper.java +++ b/src/main/java/com/power/doc/helper/JsonBuildHelper.java @@ -53,32 +53,38 @@ public class JsonBuildHelper { */ public static String buildReturnJson(DocJavaMethod docJavaMethod, ProjectDocConfigBuilder builder) { JavaMethod method = docJavaMethod.getJavaMethod(); - if (method.getReturns().isVoid() && Objects.isNull(builder.getApiConfig().getResponseBodyAdvice())) { + String responseBodyAdvice = null; + if (Objects.nonNull(builder.getApiConfig().getResponseBodyAdvice())) { + responseBodyAdvice = builder.getApiConfig().getResponseBodyAdvice().getClassName(); + } + if (method.getReturns().isVoid() && Objects.isNull(responseBodyAdvice)) { return "Doesn't return a value."; } DocletTag downloadTag = method.getTagByName(DocTags.DOWNLOAD); if (Objects.nonNull(downloadTag)) { return "File download."; } - if (method.getReturns().isEnum()) { + if (method.getReturns().isEnum() && Objects.isNull(responseBodyAdvice)) { return StringUtil.removeQuotes(String.valueOf(JavaClassUtil.getEnumValue(method.getReturns(), Boolean.FALSE))); } - if (method.getReturns().isPrimitive()) { + if (method.getReturns().isPrimitive() && Objects.isNull(responseBodyAdvice)) { String typeName = method.getReturnType().getCanonicalName(); return StringUtil.removeQuotes(DocUtil.jsonValueByType(typeName)); } - if (DocGlobalConstants.JAVA_STRING_FULLY.equals(method.getReturnType().getGenericCanonicalName())) { + if (DocGlobalConstants.JAVA_STRING_FULLY.equals(method.getReturnType().getGenericCanonicalName()) + && Objects.isNull(responseBodyAdvice)) { return "string"; } String returnTypeGenericCanonicalName = method.getReturnType().getGenericCanonicalName(); - if (Objects.nonNull(builder.getApiConfig().getResponseBodyAdvice()) + if (Objects.nonNull(responseBodyAdvice) && Objects.isNull(method.getTagByName(IGNORE_RESPONSE_BODY_ADVICE))) { - String responseBodyAdvice = builder.getApiConfig().getResponseBodyAdvice().getClassName(); - StringBuilder sb = new StringBuilder(); - sb.append(responseBodyAdvice) - .append("<") - .append(returnTypeGenericCanonicalName).append(">"); - returnTypeGenericCanonicalName = sb.toString(); + if (!returnTypeGenericCanonicalName.startsWith(responseBodyAdvice)) { + StringBuilder sb = new StringBuilder(); + sb.append(responseBodyAdvice) + .append("<") + .append(returnTypeGenericCanonicalName).append(">"); + returnTypeGenericCanonicalName = sb.toString(); + } } ApiReturn apiReturn = DocClassUtil.processReturnType(returnTypeGenericCanonicalName); String typeName = apiReturn.getSimpleName(); diff --git a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java index 790e743..be9872f 100644 --- a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java +++ b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java @@ -31,10 +31,7 @@ import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.DocTags; import com.power.doc.constants.ValidatorAnnotations; import com.power.doc.model.*; -import com.power.doc.utils.DocClassUtil; -import com.power.doc.utils.DocUtil; -import com.power.doc.utils.JavaClassUtil; -import com.power.doc.utils.JavaClassValidateUtil; +import com.power.doc.utils.*; import com.thoughtworks.qdox.model.JavaAnnotation; import com.thoughtworks.qdox.model.JavaClass; import com.thoughtworks.qdox.model.JavaField; @@ -350,6 +347,16 @@ public class ParamsBuildHelper { } else if (JavaClassValidateUtil.isCollection(subTypeName) || JavaClassValidateUtil.isArray(subTypeName)) { param.setType("array"); + if (tagsMap.containsKey(DocTags.MOCK) && StringUtil.isNotEmpty(tagsMap.get(DocTags.MOCK))) { + param.setValue(fieldValue); + if (StringUtil.isNotEmpty(comment)) { + commonHandleParam(paramList, param, isRequired, comment + appendComment, since, strRequired); + } else { + commonHandleParam(paramList, param, isRequired, NO_COMMENTS_FOUND + appendComment, since, strRequired); + } + continue; + } + if (globGicName.length > 0 && "java.util.List".equals(fieldGicName)) { fieldGicName = fieldGicName + ""; } @@ -414,6 +421,17 @@ public class ParamsBuildHelper { } } else if (JavaClassValidateUtil.isMap(subTypeName)) { + if (tagsMap.containsKey(DocTags.MOCK) && StringUtil.isNotEmpty(tagsMap.get(DocTags.MOCK))) { + param.setType("map"); + param.setValue(fieldValue); + if (StringUtil.isNotEmpty(comment)) { + commonHandleParam(paramList, param, isRequired, comment + appendComment, since, strRequired); + } else { + commonHandleParam(paramList, param, isRequired, NO_COMMENTS_FOUND + appendComment, since, strRequired); + } + continue; + } + if (StringUtil.isNotEmpty(comment)) { commonHandleParam(paramList, param, isRequired, comment + appendComment, since, strRequired); } else { diff --git a/src/main/java/com/power/doc/template/IDocBuildTemplate.java b/src/main/java/com/power/doc/template/IDocBuildTemplate.java index 104ea8d..1295ad8 100644 --- a/src/main/java/com/power/doc/template/IDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/IDocBuildTemplate.java @@ -107,10 +107,12 @@ public interface IDocBuildTemplate { if (Objects.nonNull(projectBuilder.getApiConfig().getResponseBodyAdvice()) && Objects.isNull(method.getTagByName(IGNORE_RESPONSE_BODY_ADVICE))) { String responseBodyAdvice = projectBuilder.getApiConfig().getResponseBodyAdvice().getClassName(); - returnTypeGenericCanonicalName = new StringBuffer() - .append(responseBodyAdvice) - .append("<") - .append(returnTypeGenericCanonicalName).append(">").toString(); + if (!returnTypeGenericCanonicalName.startsWith(responseBodyAdvice)) { + returnTypeGenericCanonicalName = new StringBuffer() + .append(responseBodyAdvice) + .append("<") + .append(returnTypeGenericCanonicalName).append(">").toString(); + } } Map actualTypesMap = docJavaMethod.getActualTypesMap(); ApiReturn apiReturn = DocClassUtil.processReturnType(returnTypeGenericCanonicalName); diff --git a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java index bd464b0..982fcb7 100644 --- a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java @@ -200,7 +200,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { } apiMethodDoc.setDetail(apiNoteValue); //handle headers - List apiReqParams = new SpringMVCRequestHeaderHandler().handle(method, projectBuilder); + List apiReqHeaders = new SpringMVCRequestHeaderHandler().handle(method, projectBuilder); apiMethodDoc.setType(requestMapping.getMethodType()); apiMethodDoc.setUrl(requestMapping.getUrl()); @@ -226,21 +226,21 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { apiMethodDoc.setRequestParams(apiMethodReqParam.getRequestParams()); } - List allApiReqParams; + List allApiReqHeaders; if (this.configApiReqParams != null) { final Map> reqParamMap = apiReqParamList.stream().collect(Collectors.groupingBy(ApiReqParam::getParamIn)); final List headerParamList = reqParamMap.getOrDefault(ApiReqParamInTypeEnum.HEADER.getValue(), Collections.emptyList()); - allApiReqParams = Stream.of(apiReqParams, headerParamList).filter(Objects::nonNull) + allApiReqHeaders = Stream.of(apiReqHeaders, headerParamList).filter(Objects::nonNull) .flatMap(Collection::stream).distinct().collect(Collectors.toList()); } else { - allApiReqParams = apiReqParams.stream().filter(param -> filterPath(requestMapping, param)).collect(Collectors.toList()); + allApiReqHeaders = apiReqHeaders.stream().filter(param -> filterPath(requestMapping, param)).collect(Collectors.toList()); } //reduce create in template - apiMethodDoc.setHeaders(this.createDocRenderHeaders(allApiReqParams, apiConfig.isAdoc())); - apiMethodDoc.setRequestHeaders(allApiReqParams); + apiMethodDoc.setHeaders(this.createDocRenderHeaders(allApiReqHeaders, apiConfig.isAdoc())); + apiMethodDoc.setRequestHeaders(allApiReqHeaders); String path = apiMethodDoc.getPath().split(";")[0]; String pathUrl = DocUtil.formatPathUrl(path); @@ -288,11 +288,11 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate { private boolean filterPath(RequestMapping requestMapping, ApiReqParam apiReqHeader) { if (StringUtil.isEmpty(apiReqHeader.getPathPatterns()) && StringUtil.isEmpty(apiReqHeader.getExcludePathPatterns())) { - return false; + return true; } else { boolean flag = DocPathUtil.matches(requestMapping.getShortUrl(), apiReqHeader.getPathPatterns() , apiReqHeader.getExcludePathPatterns()); - return !flag; + return flag; } } diff --git a/src/main/java/com/power/doc/utils/DocUtil.java b/src/main/java/com/power/doc/utils/DocUtil.java index 6fd8799..da02245 100644 --- a/src/main/java/com/power/doc/utils/DocUtil.java +++ b/src/main/java/com/power/doc/utils/DocUtil.java @@ -55,7 +55,6 @@ public class DocUtil { static { fieldValue.put("uuid-string", UUID.randomUUID().toString()); - fieldValue.put("uid", UUID.randomUUID().toString()); fieldValue.put("id-string", String.valueOf(RandomUtil.randomInt(1, 200))); fieldValue.put("nickname-string", enFaker.name().username()); fieldValue.put("hostname-string", faker.internet().ipV4Address()); diff --git a/src/main/java/com/power/doc/utils/JavaClassUtil.java b/src/main/java/com/power/doc/utils/JavaClassUtil.java index 34a5781..192af1d 100644 --- a/src/main/java/com/power/doc/utils/JavaClassUtil.java +++ b/src/main/java/com/power/doc/utils/JavaClassUtil.java @@ -461,15 +461,15 @@ public class JavaClassUtil { if (CollectionUtil.isEmpty(annotationValueList)) { return; } - for (int i = 0; i < annotationValueList.size(); i++) { - TypeRef annotationValue = (TypeRef) annotationValueList.get(i); - DefaultJavaParameterizedType annotationValueType = (DefaultJavaParameterizedType) annotationValue.getType(); + for (AnnotationValue annotationValue : annotationValueList) { + TypeRef typeRef = (TypeRef) annotationValue; + DefaultJavaParameterizedType annotationValueType = (DefaultJavaParameterizedType) typeRef.getType(); javaClassList.add(annotationValueType.getGenericCanonicalName()); } } private static List getAnnotationValues(List validates, JavaAnnotation javaAnnotation) { - List annotationValueList = null; + List annotationValueList = new ArrayList<>(); String simpleName = javaAnnotation.getType().getValue(); if (simpleName.equalsIgnoreCase(ValidatorAnnotations.VALIDATED)) { if (Objects.nonNull(javaAnnotation.getProperty(DocAnnotationConstants.VALUE_PROP))) { @@ -478,7 +478,6 @@ public class JavaClassUtil { annotationValueList = ((AnnotationValueList) v).getValueList(); } if (v instanceof TypeRef) { - annotationValueList = new ArrayList<>(); annotationValueList.add(v); } } @@ -489,7 +488,6 @@ public class JavaClassUtil { annotationValueList = ((AnnotationValueList) v).getValueList(); } if (v instanceof TypeRef) { - annotationValueList = new ArrayList<>(); annotationValueList.add(v); } } diff --git a/src/main/resources/template/dubbo/Dubbo.md b/src/main/resources/template/dubbo/Dubbo.md index 6434ff4..7ff203f 100644 --- a/src/main/resources/template/dubbo/Dubbo.md +++ b/src/main/resources/template/dubbo/Dubbo.md @@ -9,15 +9,13 @@ **Author:** ${author} **Version:** ${version} -<% for(doc in list){ %> +<% +for(doc in list){ +%> <%if(doc.deprecated){%> - ## ~~${doc.desc}~~ - <%}else{%> - ## ${doc.desc} - <%}%> **Definition:** ${doc.methodDefinition} @@ -33,8 +31,9 @@ Parameter|Type|Description|Required|Since ---|---|---|---|--- - -<% for(param in doc.requestParams){ %> +<% +for(param in doc.requestParams){ +%> ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} <%}%> <%}%> @@ -44,8 +43,9 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} Field | Type|Description|Since ---|---|---|--- - -<% for(param in doc.responseParams){ %> +<% +for(param in doc.responseParams){ +%> ${param.field}|${param.type}|${param.desc}|${param.version} <%}%> <%}%> diff --git a/src/main/resources/template/dubbo/DubboAllInOne.md b/src/main/resources/template/dubbo/DubboAllInOne.md index 561c9fc..3c88891 100644 --- a/src/main/resources/template/dubbo/DubboAllInOne.md +++ b/src/main/resources/template/dubbo/DubboAllInOne.md @@ -1,18 +1,17 @@ <%if(isNotEmpty(projectName)){%> - # ${projectName} - <%}%> <%if(isNotEmpty(revisionLogList)){%> -Version | Update Time | Status | Author | Description ---|---|---|---|--- + +Version|Update Time|Status|Author|Description +---|---|---|---|--- <% for(revisionLog in revisionLogList){ %> ${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks} <%}%> <%}%> <%if(isNotEmpty(dependencyList)){%> - ## Add dependency ``` @@ -30,16 +29,15 @@ for(dependency in dependencyList){ <%if(isNotEmpty(consumerConfigExample)){%> Consumer config - ``` ${consumerConfigExample} ``` - <%}%> <%}%> -<% for(api in apiDocList){ %> - +<% +for(api in apiDocList){ +%> ## ${api.desc} **URI:** ${api.uri} @@ -51,15 +49,13 @@ ${consumerConfigExample} **Author:** ${api.author} **Version:** ${api.version} -<% for(doc in api.list){ %> +<% +for(doc in api.list){ +%> <%if(doc.deprecated){%> - ### ~~${doc.desc}~~ - <%}else{%> - ### ${doc.desc} - <%}%> **Definition:** ${doc.methodDefinition} @@ -75,8 +71,9 @@ ${consumerConfigExample} Parameter|Type|Description|Required|Since ---|---|---|---|--- - -<% for(param in doc.requestParams){ %> +<% +for(param in doc.requestParams){ +%> ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} <%}%> <%}%> @@ -86,23 +83,25 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} Field | Type|Description|Since ---|---|---|--- - -<% for(param in doc.responseParams){ %> +<% +for(param in doc.responseParams){ +%> ${param.field}|${param.type}|${param.desc}|${param.version} <%}%> <%}%> -<%if(isNotEmpty(errorCodeList)){%> + +<%}%> +<%}%> +<%if(isNotEmpty(errorCodeList)){%> ## ${errorListTitle} Error code |Description ---|--- - -<% for(error in errorCodeList){ %> +<% +for(error in errorCodeList){ +%> ${error.value}|${error.desc} -<%}%> -<%}%> - <%}%> <%}%> \ No newline at end of file diff --git a/src/test/java/com/power/doc/ApiDocTest.java b/src/test/java/com/power/doc/ApiDocTest.java index 1178bbc..d1d794f 100644 --- a/src/test/java/com/power/doc/ApiDocTest.java +++ b/src/test/java/com/power/doc/ApiDocTest.java @@ -31,26 +31,27 @@ public class ApiDocTest { config.setServerUrl("http://127.0.0.1:8899"); //config.setStrict(true); config.setOpenUrl("http://demo.torna.cn/api"); - config.setAppKey("20201216788835306945118208"); - config.setAppToken("258e853573d44ef4a3e2caebdcafbc0f"); - config.setSecret("W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR"); + config.setAppKey("20210617855226428617129984"); + config.setAppToken("b3e291ed6a75452f9a467d420583082c"); + config.setSecret("^^As.tU#XpK=FATTpY