From a50b3a01cffc169e2c07a7a4566b756da160413c Mon Sep 17 00:00:00 2001 From: shalousun Date: Sun, 8 Aug 2021 21:49:46 +0800 Subject: [PATCH] release 2.2.4 --- CHANGELOG.md | 2 +- doc/List.md | 150 --------------- doc/Map.md | 171 ------------------ doc/error.md | 31 ---- doc/openapi.json | 74 -------- doc/temp.md | 130 ------------- pom.xml | 2 +- .../com/power/doc/builder/TornaBuilder.java | 10 +- .../doc/builder/rpc/RpcTornaBuilder.java | 8 +- .../doc/constants/ApiReqParamInTypeEnum.java | 12 +- .../power/doc/constants/HighlightStyle.java | 11 +- .../power/doc/constants/TornaConstants.java | 16 +- .../com/power/doc/helper/JsonBuildHelper.java | 3 +- .../power/doc/helper/ParamsBuildHelper.java | 3 +- .../java/com/power/doc/model/ApiConfig.java | 26 ++- .../com/power/doc/model/torna/EnumInfo.java | 19 +- .../doc/model/torna/TornaRequestInfo.java | 12 +- .../java/com/power/doc/utils/DocUtil.java | 8 +- .../java/com/power/doc/utils/TornaUtil.java | 47 ++--- 19 files changed, 74 insertions(+), 661 deletions(-) delete mode 100644 doc/List.md delete mode 100644 doc/Map.md delete mode 100644 doc/error.md delete mode 100644 doc/openapi.json delete mode 100644 doc/temp.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 321e78f..eac974e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ #### 版本号：2.2.4 -- 更新日期: 2021-08-04 +- 更新日期: 2021-08-08 - 更新内容： 1. 修复字典码推送torna错误 #https://gitee.com/smart-doc-team/smart-doc/issues/I43JQR。 2. 新增jsr303 @size和@length支持。 diff --git a/doc/List.md b/doc/List.md deleted file mode 100644 index 4303219..0000000 --- a/doc/List.md +++ /dev/null @@ -1,150 +0,0 @@ -关于list结构的返回json数据测试 - -# List结构 - -api-doc对于List中返回基础数据类型都是支持的 - -``` -/** - * List - * - * @return - */ -@GetMapping(value = "listString") -public List testList() { - return null; -} -``` - -api-doc生成的响应数据 - -``` -[ "ivvqah","isrz5x"] -``` - -# List>结构 - -``` -/** - * - * @return - */ -@GetMapping(value = "/map/Primitive") -public List> testMap() { - return null; -} -``` - -api-doc生成的响应数据 - -``` -[{ - "mapKey1": "o9mibj", - "mapKey2": "3dnnrn" -}] -``` - -# List>结构 - -``` -@GetMapping(value = "/map/Primitive") -public List> testMap() { - return null; -} - -``` - -相应数据省略 - -# 测试List结构 - -``` -/** - * 测试List结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public List testMap() { - return null; -} -``` - -# List>结构 - -``` -/** - * 测试List>结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public List> testMap() { - return null; -} -``` - -# List>>超复杂结构 - -``` -/** - * 测试List>>超复杂结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public List>> testMap() { - return null; -} -``` - -api-doc自动返回的数据 - -``` -[{ - "mapKey": { - "data": { - "userName": "lxh2yi", - "userAddress": "6jfp3h", - "userAge": 741 - }, - "data1": { - "userName": "1wp54g", - "userAddress": "8ul6m4", - "userAge": 550 - }, - "age": 10 - } -}] -``` - -# List,List,List>>超复杂结构 - -``` -/** - * List,List,List>> - * @return - */ -@GetMapping(value = "listString") -public List,List,List>> testListString(){ - return null; -} -``` - -# 其他复杂结构 - -``` -/** - * List,List,List>> - * - * @return - */ -@GetMapping(value = "listString") -public List,User,User>> testListString() { - return null; -} - -@GetMapping(value = "listString") -public List,Teacher,Teacher>> testListString() { - return null; -} -``` - -**注意：** api-doc为了传入的复杂泛型结构数据，做了许多情况的测试，目前基本能兼容系统开发中95%以上的List返回接口， 也提供了一些能够处理的很复杂的泛型结构，但是这种复杂的泛型结构在开发中是不被推荐的。 \ No newline at end of file diff --git a/doc/Map.md b/doc/Map.md deleted file mode 100644 index 2128d3f..0000000 --- a/doc/Map.md +++ /dev/null @@ -1,171 +0,0 @@ -Api-doc对于api中map结构数据的json化处理多组测试用例,对于map返回的json结构， 目前基本仅仅支持，String类型的key。 - -**基础数据类型：** json支持的基本java数据类型(不包含byte,包含String) - -# map使用基础数据类型 - -``` -/** - * 测试map使用基础数据类型 - * @return - */ -@GetMapping(value = "/map/Primitive") -public Map testMap() { - return null; -} -``` - -api-doc 生成的json: - -``` -{ - "mapKey1": 721, - "mapKey2": 280 -} -``` - -# map使用Object - -因为api-doc使用的是无侵入静态分析生成api文档，因此对于直接使用Object做map value的接口，api-doc无法准确的生成json。 -所以api-doc返回是会在默认json中加一段警告，使用者需要自己去修改返回数据，或者是使用显示的类型数据结构。 - -``` -/** - * 测试map使用基础数据类型 - * @return - */ -@GetMapping(value = "/map/Primitive") -public Map testMap() { - return null; -} -``` - -api-doc 生成的json: - -``` -{ - "mapKey": { - "waring": "You may use java.util.Object for Map value;Api-doc can't be handle." - } -} -``` - -# map中属于自己定义的简单数据结构 - -User对象的属性仅仅是基本数据类型 - -``` -/** - * 测试map使用自定义数据结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public Map testMap() { - return null; -} -``` - -api-doc 生成的json: - -``` -{ - "mapKey": { - "userName": "7t2ccy", - "userAddress": "3ipy7g", - "userAge": 280 - } -} -``` - -# map中属于自己定义的复杂数据结构 - -Student对象的属性有基本类型又有User类型和Map类型的属性。 - -``` -/** - * 测试map使用自定义数据结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public Map testMap() { - return null; -} -``` - -api-doc 生成的json: - -``` -{ - "mapKey": { - "stuName": "9cwzml", - "stuAge": 792, - "stuAddress": "rdfmtx", - "user": { - "userName": "fjglql", - "userAddress": "yy6vkf", - "userAge": 398 - }, - "userMap": { - "mapKey": { - "userName": "paw90w", - "userAddress": "mnmz42", - "userAge": 937 - } - }, - "user1": { - "userName": "rr3v6g", - "userAddress": "rbeorq", - "userAge": 399 - } - } -} -``` - -# Map>复杂结构 - -``` -{ - "mapKey":{ - "data":{ - "userName":"tumrit", - "userAddress":"v8fvdi", - "userAge":465 - }, - "data1":{ - "userName":"f7wbwk", - "userAddress":"brdh8j", - "userAge":345 - }, - "age":194 - } -} -``` - -# Map,N>超复杂结构 - -``` -/** - * Map,N>超复杂结构 - * @return - */ -@GetMapping(value = "/map/Primitive") -public Map,User>> testMap() { - return null; -} -``` - -# Map其他复杂结构 - -对于map的key采用多泛型的情况，目前api-doc也是支持的。 - -``` -/** - * Map,N>超复杂结构 - * @return - */ -public Map,Map,Map>> testMap() { - return null; -} -``` - -**注意：** api-doc为了传入的复杂泛型结构数据，做了许多情况的测试，目前基本能兼容系统开发中95%以上的Map返回接口， 也提供了一些能够处理的很复杂的泛型结构，但是这种复杂的泛型结构在开发中是不被推荐的。 \ No newline at end of file diff --git a/doc/error.md b/doc/error.md deleted file mode 100644 index c964f1c..0000000 --- a/doc/error.md +++ /dev/null @@ -1,31 +0,0 @@ -api-doc对Spring mvc或者SpringBoot应用的Controller接口返回做了一些强制规约，一旦在代码中使用 这些被api-doc不推荐的接口返回类型，api-doc将会直接报错。 - -# 违反规约的实例 - -## 直接返回Object - -``` -/** - * 返回object - * @return - */ -@GetMapping("/test/Object") -public Object getMe(){ - return null; -} -``` - -报错提示：Please do not return java.lang.Object directly in api interface. - -## 将非String对象作为Map的key，然后将map作为接口中返回 - -``` -/** - * 测试object的作为map的key - * @return - */ -@GetMapping("/test/map") -public Map objectMap(){ - return null; -} -``` \ No newline at end of file diff --git a/doc/openapi.json b/doc/openapi.json deleted file mode 100644 index f4c7ccd..0000000 --- a/doc/openapi.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "components": { - "schemas": { - "Pet": { - "type": "object", - "discriminator": { - "propertyName": "petType" - }, - "properties": { - "name": { - "type": "string" - }, - "petType": { - "type": "string" - } - }, - "required": [ - "name", - "petType" - ] - }, - "Cat": { - "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "huntingSkill": { - "type": "string", - "description": "The measured skill for hunting", - "default": "lazy", - "enum": [ - "clueless", - "lazy", - "adventurous", - "aggressive" - ] - } - }, - "required": [ - "huntingSkill" - ] - } - ] - }, - "Dog": { - "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "packSize": { - "type": "integer", - "format": "int32", - "description": "the size of the pack the dog is from", - "default": 0, - "minimum": 0 - } - }, - "required": [ - "packSize" - ] - } - ] - } - } - } -} \ No newline at end of file diff --git a/doc/temp.md b/doc/temp.md deleted file mode 100644 index 0101046..0000000 --- a/doc/temp.md +++ /dev/null @@ -1,130 +0,0 @@ -```java - /** - * Get fields - * - * @param cls1 The JavaClass object - * @param counter Recursive counter - * @param addedFields added fields,Field deduplication - * @return list of JavaField - */ -public static List getFields(JavaClass cls1,int counter,HashMap addedFields){ - List fieldList=new ArrayList<>(); - if(null==cls1){ - return fieldList; - }else if("Object".equals(cls1.getSimpleName())||"Timestamp".equals(cls1.getSimpleName())|| - "Date".equals(cls1.getSimpleName())||"Locale".equals(cls1.getSimpleName()) - ||"ClassLoader".equals(cls1.getSimpleName())||JavaClassValidateUtil.isMap(cls1.getFullyQualifiedName()) - ||cls1.isEnum()||"Serializable".equals(cls1.getSimpleName())){ - return fieldList; - }else{ - String className=cls1.getFullyQualifiedName(); - if(cls1.isInterface()&& - !JavaClassValidateUtil.isCollection(className)&& - !JavaClassValidateUtil.isMap(className)){ - List methods=cls1.getMethods(); - for(JavaMethod javaMethod:methods){ - String methodName=javaMethod.getName(); - int paramSize=javaMethod.getParameters().size(); - boolean enable=false; - if(methodName.startsWith("get")&&!"get".equals(methodName)&¶mSize==0){ - methodName=StringUtil.firstToLowerCase(methodName.substring(3)); - enable=true; - }else if(methodName.startsWith("is")&&!"is".equals(methodName)&¶mSize==0){ - methodName=StringUtil.firstToLowerCase(methodName.substring(2)); - enable=true; - } - if(!enable||addedFields.containsKey(methodName)){ - continue; - } - String comment=javaMethod.getComment(); - JavaField javaField=new DefaultJavaField(javaMethod.getReturns(),methodName); - DocJavaField docJavaField=DocJavaField.builder() - .setJavaField(javaField) - .setComment(comment) - .setDocletTags(javaMethod.getTags()) - .setAnnotations(javaMethod.getAnnotations()) - .setFullyQualifiedName(javaField.getType().getFullyQualifiedName()) - .setGenericCanonicalName(javaField.getType().getGenericCanonicalName()); - addedFields.put(methodName,docJavaField); - } - } - // ignore enum parent class - if(!cls1.isEnum()){ - JavaClass parentClass=cls1.getSuperJavaClass(); - getFields(parentClass,counter,addedFields); - List implClasses=cls1.getImplements(); - for(JavaType type:implClasses){ - JavaClass javaClass=(JavaClass)type; - getFields(javaClass,counter,addedFields); - } - } - Map actualJavaTypes=getActualTypesMap(cls1); - List javaMethods=cls1.getMethods(); - for(JavaMethod method:javaMethods){ - String methodName=method.getName(); - int paramSize=method.getParameters().size(); - if(methodName.startsWith("get")&&!"get".equals(methodName)&¶mSize==0){ - methodName=StringUtil.firstToLowerCase(methodName.substring(3)); - }else if(methodName.startsWith("is")&&!"is".equals(methodName)&¶mSize==0){ - methodName=StringUtil.firstToLowerCase(methodName.substring(2)); - } - if(addedFields.containsKey(methodName)){ - String comment=method.getComment(); - DocJavaField docJavaField=addedFields.get(methodName); - docJavaField.setAnnotations(method.getAnnotations()); - docJavaField.setComment(comment); - addedFields.put(methodName,docJavaField); - } - } - for(JavaField javaField:cls1.getFields()){ - String fieldName=javaField.getName(); - DocJavaField docJavaField=DocJavaField.builder(); - boolean typeChecked=false; - String gicName=javaField.getType().getGenericCanonicalName(); - String subTypeName=javaField.getType().getFullyQualifiedName(); - String actualType=null; - if(JavaClassValidateUtil.isCollection(subTypeName)&& - !JavaClassValidateUtil.isCollection(gicName)){ - String[]gNameArr=DocClassUtil.getSimpleGicName(gicName); - actualType=JavaClassUtil.getClassSimpleName(gNameArr[0]); - docJavaField.setArray(true); - typeChecked=true; - } - if(JavaClassValidateUtil.isPrimitive(subTypeName)&&!typeChecked){ - docJavaField.setPrimitive(true); - typeChecked=true; - } - if(JavaClassValidateUtil.isFile(subTypeName)&&!typeChecked){ - docJavaField.setFile(true); - typeChecked=true; - } - if(javaField.getType().isEnum()&&!typeChecked){ - docJavaField.setEnum(true); - } - for(Map.Entry entry:actualJavaTypes.entrySet()){ - String key=entry.getKey(); - JavaType value=entry.getValue(); - if(gicName.contains(key)){ - subTypeName=subTypeName.replaceAll(key,value.getFullyQualifiedName()); - gicName=gicName.replaceAll(key,value.getGenericCanonicalName()); - actualType=value.getFullyQualifiedName(); - } - } - docJavaField.setComment(javaField.getComment()) - .setJavaField(javaField).setFullyQualifiedName(subTypeName) - .setGenericCanonicalName(gicName).setActualJavaType(actualType) - .setAnnotations(javaField.getAnnotations()); - if(addedFields.containsKey(fieldName)){ - addedFields.put(fieldName,docJavaField); - continue; - } - addedFields.put(fieldName,docJavaField); - } - List parentFieldList=addedFields.values().stream() - .filter(v->Objects.nonNull(v)).collect(Collectors.toList()); - fieldList.addAll(parentFieldList); - } - return fieldList; - } - -``` \ No newline at end of file diff --git a/pom.xml b/pom.xml index 98868af..0cde2cd 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 smart-doc jar - 2.2.3 + 2.2.4 smart-doc https://github.com/smart-doc-group/smart-doc.git diff --git a/src/main/java/com/power/doc/builder/TornaBuilder.java b/src/main/java/com/power/doc/builder/TornaBuilder.java index 0774268..41b3c7f 100644 --- a/src/main/java/com/power/doc/builder/TornaBuilder.java +++ b/src/main/java/com/power/doc/builder/TornaBuilder.java @@ -95,7 +95,7 @@ public class TornaBuilder { tornaApi.setAuthor(StringUtil.isEmpty(apiConfig.getAuthor()) ? System.getProperty("user.name") : apiConfig.getAuthor()); Apis api; List apisList = new ArrayList<>(); - //添加接口数据 + //Convert ApiDoc to Apis for (ApiDoc a : apiDocs) { api = new Apis(); api.setName(StringUtils.isBlank(a.getDesc()) ? a.getName() : a.getDesc()); @@ -108,9 +108,9 @@ public class TornaBuilder { tornaApi.setCommonErrorCodes(buildErrorCode(apiConfig)); tornaApi.setApis(apisList); tornaApi.setIsReplace(apiConfig.isReplace() ? 1 : 0); - //推送文档信息 + //Build push document information Map requestJson = TornaConstants.buildParams(PUSH, new Gson().toJson(tornaApi), apiConfig); - //推送字典信息 + //Push dictionary information Map dicMap = new HashMap<>(2); List docDicts = TornaUtil.buildTornaDic(DocUtil.buildDictionary(apiConfig, builder)); if (CollectionUtil.isNotEmpty(docDicts)) { @@ -119,10 +119,10 @@ public class TornaBuilder { String dicResponseMsg = OkHttp3Util.syncPostJson(apiConfig.getOpenUrl(), new Gson().toJson(dicRequestJson)); TornaUtil.printDebugInfo(apiConfig, dicResponseMsg, dicRequestJson, ENUM_PUSH); } - //获取返回结果 + //Get the response result String responseMsg = OkHttp3Util.syncPostJson(apiConfig.getOpenUrl(), new Gson().toJson(requestJson)); - //开启调试时打印请求信息 + //Print the log of pushing documents to Torna TornaUtil.printDebugInfo(apiConfig, responseMsg, requestJson, PUSH); } diff --git a/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java b/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java index 438e579..5f7c2ac 100644 --- a/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java +++ b/src/main/java/com/power/doc/builder/rpc/RpcTornaBuilder.java @@ -108,10 +108,10 @@ public class RpcTornaBuilder { } tornaApi.setCommonErrorCodes(buildErrorCode(apiConfig)); tornaApi.setApis(apisList); - //推送文档信息 + //Build push document information Map requestJson = TornaConstants.buildParams(PUSH, new Gson().toJson(tornaApi), apiConfig); - //推送字典信息 + //Push dictionary information Map dicMap = new HashMap<>(2); List docDicts = TornaUtil.buildTornaDic(DocUtil.buildDictionary(apiConfig, builder)); @@ -122,9 +122,9 @@ public class RpcTornaBuilder { TornaUtil.printDebugInfo(apiConfig, dicResponseMsg, dicRequestJson, ENUM_PUSH); } Map dicRequestJson = TornaConstants.buildParams(ENUM_PUSH, new Gson().toJson(dicMap), apiConfig); - //获取返回结果 + //Get the response result String responseMsg = OkHttp3Util.syncPostJson(apiConfig.getOpenUrl(), new Gson().toJson(requestJson)); - //开启调试时打印请求信息 + //Print the log of pushing documents to Torna TornaUtil.printDebugInfo(apiConfig, responseMsg, requestJson, PUSH); } } diff --git a/src/main/java/com/power/doc/constants/ApiReqParamInTypeEnum.java b/src/main/java/com/power/doc/constants/ApiReqParamInTypeEnum.java index 0d1dc46..ebe88fd 100644 --- a/src/main/java/com/power/doc/constants/ApiReqParamInTypeEnum.java +++ b/src/main/java/com/power/doc/constants/ApiReqParamInTypeEnum.java @@ -1,25 +1,25 @@ package com.power.doc.constants; /** - * 请求参数所在位置 - * * @author chen qi 2021-07-15 10:55 - * **/ public enum ApiReqParamInTypeEnum { /** - * 请求头参数 + * header param */ HEADER("header"), + /** - * query 参数 + * query param */ QUERY("query"), + /** - * path参数 + * path param */ PATH("path"); + private final String value; ApiReqParamInTypeEnum(String value) { diff --git a/src/main/java/com/power/doc/constants/HighlightStyle.java b/src/main/java/com/power/doc/constants/HighlightStyle.java index 56cff92..3932c11 100644 --- a/src/main/java/com/power/doc/constants/HighlightStyle.java +++ b/src/main/java/com/power/doc/constants/HighlightStyle.java @@ -229,7 +229,7 @@ public class HighlightStyle { /** - * 随机一个 light style + * Randomly select a light style * * @param random Random * @return String of random @@ -239,7 +239,7 @@ public class HighlightStyle { } /** - * 随机一个 dark style + * Randomly select a dark style * * @param random Random * @return String of random @@ -249,7 +249,7 @@ public class HighlightStyle { } /** - * 随机一个 style + * Randomly select a style * * @param random Random * @return String of random @@ -271,10 +271,9 @@ public class HighlightStyle { } /** - * | - * 高亮样式是否存在 + * Does the highlight style exist? * - * @param style 高亮样式 + * @param style Highlight style * @return boolean */ public static boolean containsStyle(String style) { diff --git a/src/main/java/com/power/doc/constants/TornaConstants.java b/src/main/java/com/power/doc/constants/TornaConstants.java index a02a869..c76ab5e 100644 --- a/src/main/java/com/power/doc/constants/TornaConstants.java +++ b/src/main/java/com/power/doc/constants/TornaConstants.java @@ -72,7 +72,7 @@ public class TornaConstants { if (StringUtils.isNotBlank(data)) { data = URLEncoder.encode(data, "utf-8"); } - // 公共参数 + // Public request parameters for pushing documents to Torna param.put("name", name); param.put("app_key", config.getAppKey()); param.put("data", data); @@ -112,23 +112,16 @@ public class TornaConstants { } /** - * 生成md5,全部大写 + * Generate md5 and convert to uppercase * - * @param message 消息 + * @param message message * @return String */ public static String md5(String message) { try { - // 1 创建一个提供信息摘要算法的对象，初始化为md5算法对象 MessageDigest md = MessageDigest.getInstance("MD5"); - - // 2 将消息变成byte数组 byte[] input = message.getBytes(); - - // 3 计算后获得字节数组,这就是那128位了 byte[] buff = md.digest(input); - - // 4 把数组每一字节（一个字节占八位）换成16进制连成md5字符串 return byte2hex(buff); } catch (Exception e) { throw new RuntimeException(e); @@ -136,8 +129,7 @@ public class TornaConstants { } /** - * 二进制转十六进制字符串 - * + * Convert byte array to hex * @param bytes byte array * @return String */ diff --git a/src/main/java/com/power/doc/helper/JsonBuildHelper.java b/src/main/java/com/power/doc/helper/JsonBuildHelper.java index cd88296..a58bfd2 100644 --- a/src/main/java/com/power/doc/helper/JsonBuildHelper.java +++ b/src/main/java/com/power/doc/helper/JsonBuildHelper.java @@ -122,7 +122,6 @@ public class JsonBuildHelper { public static String buildJson(String typeName, String genericCanonicalName, boolean isResp, int counter, Map registryClasses, ProjectDocConfigBuilder builder) { - //存储泛型所对应的实体类 Map genericMap = new HashMap<>(10); JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(typeName); ApiConfig apiConfig = builder.getApiConfig(); @@ -153,7 +152,7 @@ public class JsonBuildHelper { data0.append("{"); String[] globGicName = DocClassUtil.getSimpleGicName(genericCanonicalName); - //添加泛型对应关系 + JavaClassUtil.genericParamMap(genericMap, cls, globGicName); StringBuilder data = new StringBuilder(); if (JavaClassValidateUtil.isCollection(typeName) || JavaClassValidateUtil.isArray(typeName)) { diff --git a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java index 49c27ac..3bec442 100644 --- a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java +++ b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java @@ -53,7 +53,6 @@ public class ParamsBuildHelper { Map registryClasses, ProjectDocConfigBuilder projectBuilder, List groupClasses, int pid, boolean jsonRequest) { - //存储泛型所对应的实体类 Map genericMap = new HashMap<>(10); if (StringUtil.isEmpty(className)) { @@ -80,7 +79,7 @@ public class ParamsBuildHelper { String simpleName = DocClassUtil.getSimpleName(className); String[] globGicName = DocClassUtil.getSimpleGicName(className); JavaClass cls = projectBuilder.getClassByName(simpleName); - //如果存在泛型 则将泛型与类名的对应关系存起来 + JavaClassUtil.genericParamMap(genericMap, cls, globGicName); List fields = JavaClassUtil.getFields(cls, 0, new LinkedHashMap<>()); if (JavaClassValidateUtil.isPrimitive(simpleName)) { diff --git a/src/main/java/com/power/doc/model/ApiConfig.java b/src/main/java/com/power/doc/model/ApiConfig.java index 22e9925..44f9c95 100644 --- a/src/main/java/com/power/doc/model/ApiConfig.java +++ b/src/main/java/com/power/doc/model/ApiConfig.java @@ -310,35 +310,39 @@ public class ApiConfig { * Torna appKey */ private String appKey; + /** * Torna Secret */ private String secret; + /** * Torna appToken */ private String appToken; + /** * Torna openUrl */ private String openUrl; /** - * 调试环境名称 + * Debugging environment name */ private String debugEnvName; + /** - * 调试环境请求路径 + * Url of the debugging environment */ private String debugEnvUrl; /** - * torna调试开关 + * Show log when pushing document to torna */ private boolean tornaDebug = true; /** - * 推送人 + * The operator who pushes the document to Torna */ private String author; @@ -347,6 +351,12 @@ public class ApiConfig { */ private String framework; + /** + * replace old document while push to torna + * @since 2.2.4 + */ + private boolean replace; + public String getPathPrefix() { return pathPrefix; } @@ -836,6 +846,14 @@ public class ApiConfig { this.framework = framework; } + public boolean isReplace() { + return replace; + } + + public void setReplace(boolean replace) { + this.replace = replace; + } + @Override public String toString() { final StringBuilder sb = new StringBuilder("{"); diff --git a/src/main/java/com/power/doc/model/torna/EnumInfo.java b/src/main/java/com/power/doc/model/torna/EnumInfo.java index 1bb76a0..dffc971 100644 --- a/src/main/java/com/power/doc/model/torna/EnumInfo.java +++ b/src/main/java/com/power/doc/model/torna/EnumInfo.java @@ -25,25 +25,14 @@ package com.power.doc.model.torna; import java.util.List; /** - * @author: xingzi 2021/2/25 12:13 + * @author xingzi 2021/2/25 12:13 **/ public class EnumInfo { - /** - * "enumInfo": { - * "name": "支付枚举", - * "description": "支付状态", - * "items": [ - * { - * "name": "WAIT_PAY", - * "type": "string", - * "value": "0", - * "description": "未支付" - * } - * ] - * } - */ + private String name; + private String description; + private List items; public String getName() { diff --git a/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java b/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java index 4a07701..8709711 100644 --- a/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java +++ b/src/main/java/com/power/doc/model/torna/TornaRequestInfo.java @@ -29,9 +29,9 @@ import java.net.URLDecoder; import java.util.HashMap; /** - * torna请求日志信息 + * Print the log of pushing documents to Torna * - * @author: xingzi 2021/3/20 22:11 + * @author xingzi 2021/3/20 22:11 **/ public class TornaRequestInfo { private String code; @@ -92,18 +92,16 @@ public class TornaRequestInfo { public String buildInfo() { StringBuilder sb = new StringBuilder(); sb.append("---------------------------START---------------------------\n") - .append("接口名: ") + .append("API: ") .append(category) .append("\n") - .append("请求数据: \n") + .append("Request: \n") .append(TornaConstants.GSON.toJson(requestInfo)) .append("\n") - .append("返回结果: \n") + .append("Response: \n") .append(TornaConstants.GSON.fromJson(responseInfo, HashMap.class)) .append("\n") .append("---------------------------END---------------------------\n"); - - try { return URLDecoder.decode(sb.toString(), "utf-8"); } catch (UnsupportedEncodingException e) { diff --git a/src/main/java/com/power/doc/utils/DocUtil.java b/src/main/java/com/power/doc/utils/DocUtil.java index d3d4a90..e1a69c4 100644 --- a/src/main/java/com/power/doc/utils/DocUtil.java +++ b/src/main/java/com/power/doc/utils/DocUtil.java @@ -186,7 +186,7 @@ public class DocUtil { } /** - * 是否是合法的java类名称 + * valid java class name * * @param className class nem * @return boolean @@ -325,10 +325,10 @@ public class DocUtil { /** - * 分割url + * Split url * - * @param url 待分割的url - * @return url列表 + * @param url URL to be divided + * @return list of url */ public static List split(String url) { char[] chars = url.toCharArray(); diff --git a/src/main/java/com/power/doc/utils/TornaUtil.java b/src/main/java/com/power/doc/utils/TornaUtil.java index d4bca0f..45c17db 100644 --- a/src/main/java/com/power/doc/utils/TornaUtil.java +++ b/src/main/java/com/power/doc/utils/TornaUtil.java @@ -21,11 +21,10 @@ import java.util.Map; public class TornaUtil { public static boolean setDebugEnv(ApiConfig apiConfig, TornaApi tornaApi) { - //是否设置测试环境 boolean hasDebugEnv = StringUtils.isNotBlank(apiConfig.getDebugEnvName()) && StringUtils.isNotBlank(apiConfig.getDebugEnvUrl()); - //设置测试环境 + //Set up the test environment List debugEnvs = new ArrayList<>(); if (hasDebugEnv) { DebugEnv debugEnv = new DebugEnv(); @@ -37,9 +36,9 @@ public class TornaUtil { return hasDebugEnv; } - public static void printDebugInfo(ApiConfig apiConfig, String responseMsg, Map requestJson,String category) { + public static void printDebugInfo(ApiConfig apiConfig, String responseMsg, Map requestJson, String category) { if (apiConfig.isTornaDebug()) { - String sb = "配置信息列表: \n" + + String sb = "Configuration information : \n" + "OpenUrl: " + apiConfig.getOpenUrl() + "\n" + @@ -73,10 +72,10 @@ public class TornaUtil { * @return List of Api */ public static List buildApis(List apiMethodDocs, boolean hasDebugEnv) { - //参数列表 + //Parameter list List apis = new ArrayList<>(); Apis methodApi; - //遍历分类接口 + //Iterative classification interface for (ApiMethodDoc apiMethodDoc : apiMethodDocs) { methodApi = new Apis(); methodApi.setIsFolder(TornaConstants.NO); @@ -119,10 +118,10 @@ public class TornaUtil { * @return List of Api */ public static List buildDubboApis(List apiMethodDocs) { - //参数列表 + //Parameter list List apis = new ArrayList<>(); Apis methodApi; - //遍历分类接口 + //Iterative classification interface for (JavaMethodDoc apiMethodDoc : apiMethodDocs) { methodApi = new Apis(); methodApi.setIsFolder(TornaConstants.NO); @@ -145,16 +144,10 @@ public class TornaUtil { /** * build request header * - * @param apiReqParams 请求头参数列表 + * @param apiReqParams Request header parameter list * @return List of HttpParam */ public static List buildHerder(List apiReqParams) { - /** - * name": "token", - * "required": "1", - * "example": "iphone12", - * "description": "商品名称描述" - */ HttpParam httpParam; List headers = new ArrayList<>(); for (ApiReqParam header : apiReqParams) { @@ -171,30 +164,12 @@ public class TornaUtil { /** * build request response params * - * @param apiParams 参数列表 + * @param apiParams Param list * @return List of HttpParam */ public static List buildParams(List apiParams) { HttpParam httpParam; List bodies = new ArrayList<>(); - /** - * "name": "goodsName", - * "type": "string", - * "required": "1", - * "maxLength": "128", - * "example": "iphone12", - * "description": "商品名称描述", - * "parentId": "", - * "enumInfo": { - * "name": "支付枚举", - * "description": "支付状态", - * "items": [ - * { - * "name": "WAIT_PAY", - * "type": "string", - * "value": "0", - * "description": "未支付" - */ for (ApiParam apiParam : apiParams) { httpParam = new HttpParam(); httpParam.setName(apiParam.getField()); @@ -240,12 +215,12 @@ public class TornaUtil { public static List buildTornaDic(List apiDocDicts) { List dics = new ArrayList<>(); - TornaDic tornaDic ; + TornaDic tornaDic; if (CollectionUtil.isNotEmpty(apiDocDicts)) { for (ApiDocDict doc : apiDocDicts) { tornaDic = new TornaDic(); tornaDic.setName(doc.getTitle()) - // .setDescription(doc.getTitle()) + // .setDescription(doc.getTitle()) .setItems(buildTornaDicItems(doc.getDataDictList())); dics.add(tornaDic); }