diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/Context.java b/apidoc-core/src/main/java/com/kim/apidoc/core/Context.java index 4b2dc19636970a6cab49335f9bd8c3f1e3f4d42d..bb58954d4a3088eb21f9b5d8553b48c6c4af5266 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/Context.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/Context.java @@ -3,9 +3,7 @@ package com.kim.apidoc.core; import com.google.common.collect.Lists; import com.google.common.collect.Maps; import com.kim.apidoc.core.common.helper.FileHelper; -import com.kim.apidoc.core.render.AsciiDocRender; import com.kim.apidoc.core.render.MarkdownRender; -import com.kim.apidoc.core.render.PostmanRender; import com.kim.apidoc.core.render.ProjectRender; import lombok.Getter; import lombok.Setter; @@ -54,8 +52,8 @@ public class Context { */ @Setter private List renders = Lists.newArrayList( - new AsciiDocRender(), - new PostmanRender(), + //new AsciiDocRender(), + //new PostmanRender(), new MarkdownRender()); /** diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java index 88debb1c4ca8c97a790e642eab22d527f9430da8..9aecef016635c447d5f4b279cb8852a7eee8b463 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/description/TypeDescription.java @@ -1,8 +1,11 @@ package com.kim.apidoc.core.common.description; -import com.kim.apidoc.core.schema.Row; -import com.kim.apidoc.core.common.helper.StringHelper; +import com.github.javaparser.ast.comments.Comment; +import com.github.javaparser.javadoc.Javadoc; import com.google.common.collect.Lists; +import com.kim.apidoc.core.common.helper.CommentHelper; +import com.kim.apidoc.core.common.helper.StringHelper; +import com.kim.apidoc.core.schema.Row; import lombok.Getter; import lombok.Setter; @@ -168,9 +171,9 @@ public abstract class TypeDescription { * * @return the collection */ - public Collection rows() { - String key = fullKey(); - if (StringHelper.isBlank(key)) { + public Collection rows(String requestParameterType) { + String fullKey = fullKey(); + if (StringHelper.isBlank(fullKey)) { return Lists.newArrayList(); } String def; @@ -186,7 +189,26 @@ public abstract class TypeDescription { condition.append("required=").append(required); } - return Lists.newArrayList(new Row(key, type,false, condition.toString(), def, remark)); + return Lists.newArrayList(new Row(key, type, false, condition.toString(), def, remark, requestParameterType)); + } + + + /** + * Rows collection. + * + * @return the collection + */ + public Collection rows() { + return rows(null); + } + + public void accept(Comment comment) { + if (!comment.isJavadocComment()) { + setRemark(comment.getContent()); + return; + } + Javadoc javadoc = comment.asJavadocComment().parse(); + setRemark(CommentHelper.getDescription(javadoc.getDescription())); } } diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/common/helper/StringHelper.java b/apidoc-core/src/main/java/com/kim/apidoc/core/common/helper/StringHelper.java index b6c309325f759de0455d172c5b11845bea46b043..14f9f4e7d1f54a4f79eb292436ab526338b8f908 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/common/helper/StringHelper.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/common/helper/StringHelper.java @@ -13,26 +13,26 @@ public class StringHelper { } public static boolean isBlank(Object text) { - if(text instanceof String){ + if (text instanceof String) { return isBlank(((String) text)); } return isBlank(String.valueOf(text)); } public static boolean nonBlank(Object text) { - if(text instanceof String){ + if (text instanceof String) { return nonBlank(((String) text)); } return nonBlank(String.valueOf(text)); } - public static String join(String delimiter, String ... values){ + public static String join(String delimiter, String... values) { StringBuilder builder = new StringBuilder(); for (String value : values) { - if(isBlank(value)){ + if (isBlank(value)) { continue; } - if(builder.length()>0){ + if (builder.length() > 0) { builder.append(delimiter); } builder.append(value); diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/ObjectTypeResolver.java b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/ObjectTypeResolver.java index cee038cca20dd26c30e985ae28d10eaefaadc543..8a9bf3786a868f0bbc024a066ed1e89c43363143 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/ObjectTypeResolver.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/ObjectTypeResolver.java @@ -3,6 +3,7 @@ package com.kim.apidoc.core.resolver; import com.github.javaparser.resolution.declarations.ResolvedFieldDeclaration; import com.github.javaparser.resolution.types.ResolvedReferenceType; import com.github.javaparser.resolution.types.ResolvedType; +import com.github.javaparser.symbolsolver.javaparsermodel.declarations.JavaParserClassDeclaration; import com.kim.apidoc.core.ApiDoc; import com.kim.apidoc.core.common.description.ObjectTypeDescription; import com.kim.apidoc.core.common.description.TypeDescription; @@ -27,15 +28,16 @@ public class ObjectTypeResolver implements TypeResolver { ObjectTypeDescription typeDescription = new ObjectTypeDescription(); typeDescription.setType(referenceType.getTypeDeclaration().getName()); + ((JavaParserClassDeclaration) referenceType.getTypeDeclaration()).getWrappedNode().getComment().ifPresent(typeDescription::accept); //类型解析缓冲池，防止循环引用 - if(!ReferenceContext.getInstance().push(referenceType.describe())){ + if (!ReferenceContext.getInstance().push(referenceType.describe())) { return typeDescription; } //解析父类属性，并合并至当前 for (ResolvedReferenceType directAncestor : referenceType.getDirectAncestors()) { TypeDescription ancestorDescription = ApiDoc.getInstance().getTypeResolvers().resolve(directAncestor); - if(ancestorDescription.isAvailable() && ancestorDescription.isObject()){ + if (ancestorDescription.isAvailable() && ancestorDescription.isObject()) { typeDescription.merge(ancestorDescription.asObject()); } } @@ -43,19 +45,19 @@ public class ObjectTypeResolver implements TypeResolver { //TODO fix use access method for (ResolvedFieldDeclaration declaredField : referenceType.getTypeDeclaration().getDeclaredFields()) { - if(declaredField.isStatic()){ + if (declaredField.isStatic()) { continue; } ResolvedType fieldType = declaredField.getType(); - if(fieldType.isReferenceType()){ + if (fieldType.isReferenceType()) { //将父类的T，传递给 属性的T - fieldType = TypeParameterHelper.useClassTypeParameter(referenceType,fieldType.asReferenceType()); + fieldType = TypeParameterHelper.useClassTypeParameter(referenceType, fieldType.asReferenceType()); } - if(declaredField.getType().isTypeVariable()){ + if (declaredField.getType().isTypeVariable()) { //类型为T，这种泛型 Optional optional = TypeParameterHelper.getTypeParameter(referenceType, declaredField.getType().asTypeParameter().getName()); - if(optional.isPresent()){ + if (optional.isPresent()) { fieldType = optional.get(); } } @@ -71,7 +73,7 @@ public class ObjectTypeResolver implements TypeResolver { fieldDescription.getCondition().append(validation).append(" "); } //查找字段初始化值 - FieldHelper.getInitializer(declaredField).ifPresent(expr-> fieldDescription.setDefaultValue(ExpressionHelper.getValue(expr))); + FieldHelper.getInitializer(declaredField).ifPresent(expr -> fieldDescription.setDefaultValue(ExpressionHelper.getValue(expr))); typeDescription.add(fieldDescription); } diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/PrimitiveTypeResolver.java b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/PrimitiveTypeResolver.java index 36e4123488faac418220dd5146475ecd405ecb6f..fde1fe2c8f605609fb9c3f660f05cbc5845d8c0f 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/PrimitiveTypeResolver.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/PrimitiveTypeResolver.java @@ -6,22 +6,8 @@ import com.github.javaparser.resolution.types.ResolvedType; import com.google.common.collect.ImmutableList; public class PrimitiveTypeResolver implements TypeResolver { - @Override - public boolean accept(ResolvedType type) { - return type.isPrimitive() || isBoxing(type); - } - - @Override - public TypeDescription resolve(ResolvedType type) { - if(type.isPrimitive()){ - return new PrimitiveTypeDescription(type.asPrimitive()); - }else{ - return new PrimitiveTypeDescription(type.asReferenceType()); - } - } - - private static boolean isBoxing(ResolvedType type){ - if(!type.isReferenceType()){ + private static boolean isBoxing(ResolvedType type) { + if (!type.isReferenceType()) { return false; } String id = type.asReferenceType().getId(); @@ -37,4 +23,18 @@ public class PrimitiveTypeResolver implements TypeResolver { ).contains(id); } + @Override + public boolean accept(ResolvedType type) { + return type.isPrimitive() || isBoxing(type); + } + + @Override + public TypeDescription resolve(ResolvedType type) { + if (type.isPrimitive()) { + return new PrimitiveTypeDescription(type.asPrimitive()); + } else { + return new PrimitiveTypeDescription(type.asReferenceType()); + } + } + } diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/TypeResolvers.java b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/TypeResolvers.java index bc220d9e42a5f28d8f963f9cec703d8286d2aa0f..485847832bad4e4c406dd5ef8dbdeffff2d3dc73 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/TypeResolvers.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/resolver/TypeResolvers.java @@ -34,55 +34,57 @@ public class TypeResolvers { /** * 获取类型信息 + * * @param type * @return */ - public TypeDescription resolve(Type type){ - try{ + public TypeDescription resolve(Type type) { + try { ResolvedType resolvedType = type.resolve(); return resolve(resolvedType); - } catch (UnsolvedSymbolException e){ + } catch (UnsolvedSymbolException e) { //解析失败时，尝试降级，使用名称解析 return nameResolve(type); - } catch (Exception e){ - log.error(e.getMessage(),e); + } catch (Exception e) { + log.error(e.getMessage(), e); } return new UnAvailableTypeDescription(); } /** * 解析类型信息 + * * @param type * @return */ - public TypeDescription resolve(ResolvedType type){ + public TypeDescription resolve(ResolvedType type) { for (TypeResolver typeResolver : resolvers) { - if(typeResolver.accept(type)){ + if (typeResolver.accept(type)) { return typeResolver.resolve(type); } } - if(objectTypeResolver.accept(type)){ + if (objectTypeResolver.accept(type)) { return objectTypeResolver.resolve(type); } return new UnAvailableTypeDescription(); } - public TypeDescription nameResolve(Type type){ + public TypeDescription nameResolve(Type type) { String id = TypeNameHelper.getName(type); for (TypeNameResolver nameResolver : nameResolvers) { if (nameResolver.accept(id)) { return nameResolver.resolve(type); } } - log.warn("type({}) resolve failed",id); + log.warn("type({}) resolve failed", id); return new UnAvailableTypeDescription(); } - public void addResolver(TypeResolver typeResolver){ + public void addResolver(TypeResolver typeResolver) { resolvers.add(typeResolver); } - public void addNameResolver(TypeNameResolver nameResolver){ + public void addNameResolver(TypeNameResolver nameResolver) { nameResolvers.add(nameResolver); } diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/schema/RequestParameterType.java b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/RequestParameterType.java new file mode 100644 index 0000000000000000000000000000000000000000..dc17e8a10859ed9bff5ce170e92855bdbb57ce56 --- /dev/null +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/RequestParameterType.java @@ -0,0 +1,23 @@ +package com.kim.apidoc.core.schema; + +/** + * 请求参数枚举类型 + * + * @author duanledexianxianxian + * @date 2020 /3/29 0:37 + * @since 1.0.0 + */ +public enum RequestParameterType { + /** + * 查询参数. + */ + QUERY, + /** + * 路径参数. + */ + PATH, + /** + * 请求参数体. + */ + BODY +} diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Row.java b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Row.java index 22bdbd6d5c215caad1f966714909407eff119dbf..9d3a51b30779eac3b17dfedc7fd4e7c391d0e4ac 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Row.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Row.java @@ -40,6 +40,12 @@ public class Row { */ String remark; + /** + * 请求参数类型 + */ + String requestParameterType; + + /** * Instantiates a new Row. * diff --git a/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Section.java b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Section.java index 4f1c71949318541deab7af61f58a870a57cb969c..cd039399e339a8374b8c921252083bf41b8c8b48 100644 --- a/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Section.java +++ b/apidoc-core/src/main/java/com/kim/apidoc/core/schema/Section.java @@ -44,6 +44,7 @@ public class Section extends Node { * The Query parameter. */ boolean queryParameter = true; + /** * The Request rows. */ diff --git a/apidoc-core/src/main/resources/templates/markdown.ftl b/apidoc-core/src/main/resources/templates/markdown.ftl index f1571b49b651c2ccf7da851932a095014d6305ba..1d669039fae9ce0c5cd44e3d30b215661861a5bb 100644 --- a/apidoc-core/src/main/resources/templates/markdown.ftl +++ b/apidoc-core/src/main/resources/templates/markdown.ftl @@ -56,11 +56,11 @@ ${section.getParameterString()} <#-- 请求参数table列表--> <#if section.requestRows?? && (section.requestRows?size>0)> -**Query** -| Field | Type | Required | Condition | Default | Description | -| :------- | :----- | :-------- |:-------- | :------ | :---------- | +**Request** +| Field | Type | Request Type | Required | Condition | Default | Description | +| :------- | :----- | :----- |:-------- |:-------- | :------ | :---------- | <#list section.requestRows as rowKey,rowValue> -| ${rowValue.key!''} | ${rowValue.type!''} | ${rowValue.required?string('true','false')} | ${rowValue.condition!''} | ${rowValue.def!''} | ${rowValue.remark!''} | +| ${rowValue.key!''} | ${rowValue.type!''} | ${rowValue.requestParameterType!''} |${rowValue.required?string('true','false')} | ${rowValue.condition!''} | ${rowValue.def!''} | ${rowValue.remark!''} | <#-- 响应--> diff --git a/apidoc-springmvc/src/main/java/com/kim/apidoc/springmvc/SpringParser.java b/apidoc-springmvc/src/main/java/com/kim/apidoc/springmvc/SpringParser.java index 0f4fc8ebbbb1c9076291ba8d3307d8065b071f2e..d73f36428daed2d0bd912ab3a614c35ef0d9fe85 100644 --- a/apidoc-springmvc/src/main/java/com/kim/apidoc/springmvc/SpringParser.java +++ b/apidoc-springmvc/src/main/java/com/kim/apidoc/springmvc/SpringParser.java @@ -22,6 +22,8 @@ import com.github.javaparser.ast.expr.Expression; import java.util.List; import java.util.Optional; +import static com.kim.apidoc.core.schema.RequestParameterType.*; + /** * spring 解析 @@ -43,7 +45,6 @@ public class SpringParser implements ParserStrategy { public static final String EXT_URI = "uri"; - @Override public String name() { return FRAMEWORK; @@ -157,6 +158,7 @@ public class SpringParser implements ParserStrategy { if (ParameterHelper.isPathVariable(parameter)) { section.getPathVariable().put(parameter.getNameAsString(), ""); Row row = new Row(); + row.setRequestParameterType(PATH.name()); row.setKey(parameter.getNameAsString()); row.setType(parameter.getType().toString()); // 路径参数必填 @@ -235,7 +237,7 @@ public class SpringParser implements ParserStrategy { } else if (description.isObject()) { section.setParameter(description.asObject().getValue()); } - section.addRequestRows(description.rows()); + section.addRequestRows(description.rows(BODY.name())); } break; } @@ -294,7 +296,7 @@ public class SpringParser implements ParserStrategy { } } section.setParameter(objectTypeDescription.getValue()); - section.addRequestRows(objectTypeDescription.rows()); + section.addRequestRows(objectTypeDescription.rows(QUERY.name())); } /** diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java index 317cda936b52cebce78a4ad16768755070202652..9724a8f4f4903982853cd260b60922bea6c29059 100644 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java +++ b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/common/User.java @@ -8,10 +8,12 @@ import javax.validation.constraints.Min; import javax.validation.constraints.NotBlank; import javax.validation.constraints.NotNull; import java.util.Date; -import java.util.List; /** * 用户对象 + * + * @author fengyuchenglun + * @version 1.0.0 */ @Setter @Getter diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java index 5f202ad90e567880160fb93003c974da825069cd..5a01cb0972232dc9e05415d63977e4cfadfef64f 100644 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java +++ b/apidoc-springmvc/src/test/java/com/kim/apidoc/example/spring/advanced/KimUserController.java @@ -3,8 +3,8 @@ package com.kim.apidoc.example.spring.advanced; import com.kim.apidoc.example.annotation.KimController; import com.kim.apidoc.example.common.ResultData; import com.kim.apidoc.example.common.User; +import com.kim.apidoc.example.common.UserQuery; import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -25,11 +25,11 @@ public class KimUserController { * 用户详情信息 * 主动根据id获取用户的信息 * - * @param id 用户编号 - * @return 用户数据 + * @param userQuery the user query + * @return result data */ @GetMapping(value = "/{id}") - public ResultData detail(@PathVariable String id) { + public ResultData detail(UserQuery userQuery) { User user = new User(); return ResultData.ok(user); } diff --git a/apidoc-springmvc/src/test/java/com/kim/apidoc/springmvc/SpringTest.java b/apidoc-springmvc/src/test/java/com/kim/apidoc/springmvc/SpringTest.java index 824168dc587a2d69e3c03bd4eed31e6601f1ec2d..23b6e0d983d6a4de9e38c0b0e3ec12366c68f807 100644 --- a/apidoc-springmvc/src/test/java/com/kim/apidoc/springmvc/SpringTest.java +++ b/apidoc-springmvc/src/test/java/com/kim/apidoc/springmvc/SpringTest.java @@ -17,7 +17,7 @@ public class SpringTest { Context context = new Context(); context.setId("test"); context.setName("测试项目"); - context.addSource(Paths.get("F:\\@project@\\@dianli@\\tool\\apidoc\\apidoc-springmvc\\src\\test\\java")); + context.addSource(Paths.get("K:\\@project-dianli@\\tool\\apidoc\\apidoc-springmvc\\src\\test\\java")); // context.setCss("https://darshandsoni.com/asciidoctor-skins/css/monospace.css"); ApiDoc apigcc = new ApiDoc(context);