Merge branch 'dev'

This commit is contained in:
oppofind 2020-09-01 23:18:51 +08:00
commit e48de4a572
7 changed files with 74 additions and 67 deletions

View File

@ -1,5 +1,5 @@
### 当前使用版本(必须填写清楚,否则不予处理)
注意请自行从maven仓库或者是github tag确认你当前使用的是最新版的smart-doc或者相关插件
注意请自行从maven仓库或者是[github](https://github.com/smart-doc-group/smart-doc) tag确认你当前使用的是最新版的smart-doc或者相关插件
历史版本的问题官方将拒绝处理。
### 该问题是怎么引起的(如果最新版本已经修复的,会直接关闭)

View File

@ -1 +1 @@
gitee不接收pull request,请前往github
gitee不接收pull request,请前往[github](https://github.com/smart-doc-group/smart-doc)

View File

@ -3,9 +3,9 @@ name: Feature Request 💡
about: Suggest a new idea for the project.
labels: enhancement
---
## Summary
## Summary(关于这个pr的描述)
Brief explanation of the feature.
### Basic example
### Basic example(pr的用例)
If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable.
### Motivation
### Motivation(提出这个pr目的)
Why are we doing this? What use cases does it support? What is the expected outcome?

10
.travis.yml Normal file
View File

@ -0,0 +1,10 @@
language: java
jdk:
- oraclejdk8
install: mvn install -DskipTests=true -Dmaven.javadoc.skip=true
script: mvn test
after_success:
- mvn clean cobertura:cobertura coveralls:report
env:
global:
secure: xxx

View File

@ -28,14 +28,14 @@ $\color{red}{我因不将就而诞生,用了无数个日日夜夜来成长,
- 支持maven、gradle插件式轻松集成。
- 支持Apache Dubbo RPC接口文档生成。
## Getting started
smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/sunyurepository/api-doc-test.git)。
smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/smart-doc-team/api-doc-test.git)。
```
# git clone https://gitee.com/sunyurepository/api-doc-test.git
# git clone https://gitee.com/smart-doc-team/api-doc-test.git
```
你可以启动这个Spring Boot的项目然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。
### Add Maven plugin
smart-doc官方目前已经开发完成[maven插件](https://gitee.com/sunyurepository/smart-doc-maven-plugin)
和[gradle插件](https://gitee.com/sunyurepository/smart-doc-gradle-plugin)你可以根据自己的构建工具来选择使用maven插件或者是gradle插件。
smart-doc官方目前已经开发完成[maven插件](https://gitee.com/smart-doc-team/smart-doc-maven-plugin)
和[gradle插件](https://gitee.com/smart-doc-team/smart-doc-gradle-plugin)你可以根据自己的构建工具来选择使用maven插件或者是gradle插件。
#### add plugin
```
<plugin>
@ -189,17 +189,17 @@ mvn -Dfile.encoding = UTF-8 smart-doc:rpc-adoc
```
**注意:** 尤其在window系统下如果实际使用maven命令行执行文档生成可能会出现乱码因此需要在执行时指定`-Dfile.encoding=UTF-8`。
#### Use Idea
![idea中smart-doc-maven插件使用](https://gitee.com/sunyurepository/smart-doc-maven-plugin/raw/master/images/idea.png "maven_plugin_tasks.png")
![idea中smart-doc-maven插件使用](https://gitee.com/smart-doc-team/smart-doc-maven-plugin/raw/master/images/idea.png "maven_plugin_tasks.png")
### Use gradle plugin
如果你使用gradle来构建项目你可以参考gradle插件的使用文档来集成
[smart-doc-gradle-plugin](https://gitee.com/sunyurepository/smart-doc-gradle-plugin/blob/master/README_CN.md)
[smart-doc-gradle-plugin](https://gitee.com/smart-doc-team/smart-doc-gradle-plugin/blob/master/README_CN.md)
### Use Junit Test
从smart-doc 1.7.9开始官方提供了maven插件使用smart-doc的maven插件后不再需要创建单元测试。
[单元测试生成文档](https://gitee.com/sunyurepository/smart-doc/wikis/单元测试集成smart-doc?sort_id=1990284)
[单元测试生成文档](https://gitee.com/smart-doc-team/smart-doc/wikis/单元测试集成smart-doc?sort_id=1990284)
### Generated document example
[点击查看文档生成文档效果图](https://gitee.com/sunyurepository/smart-doc/wikis/文档效果图?sort_id=1652819)
[点击查看文档生成文档效果图](https://gitee.com/smart-doc-team/smart-doc/wikis/文档效果图?sort_id=1652819)
## Building
如果你需要自己构建smart-doc那可以使用下面命令构建需要依赖Java 1.8。
```
@ -219,22 +219,22 @@ mvn clean install -Dmaven.test.skip=true
- [@maliqiang](https://github.com/maliqiang)
## Other reference
- [smart-doc功能使用介绍](https://my.oschina.net/u/1760791/blog/2250962)
- [smart-doc官方wiki](https://gitee.com/sunyurepository/smart-doc/wikis/Home?sort_id=1652800)
- [smart-doc官方wiki](https://gitee.com/smart-doc-team/smart-doc/wikis/Home?sort_id=1652800)
## License
Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://gitee.com/sunyurepository/smart-doc/blob/master/LICENSE) file for details.
Smart-doc is under the Apache 2.0 license. See the [LICENSE](https://gitee.com/smart-doc-team/smart-doc/blob/master/LICENSE) file for details.
**注意:** smart-doc源代码文件全部带有版权注释使用关键代码二次开源请保留原始版权否则后果自负
## Who is using
> 排名不分先后,更多接入公司,欢迎在[https://gitee.com/sunyurepository/smart-doc/issues/I1594T](https://gitee.com/sunyurepository/smart-doc/issues/I1594T)登记(仅供开源用户参考)
> 排名不分先后,更多接入公司,欢迎在[https://gitee.com/smart-doc-team/smart-doc/issues/I1594T](https://gitee.com/smart-doc-team/smart-doc/issues/I1594T)登记(仅供开源用户参考)
![IFLYTEK](https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/iflytek.png)
&nbsp;&nbsp;<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/oneplus.png" title="一加" width="83px" height="83px"/>
&nbsp;&nbsp;<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/xiaomi.png" title="小米" width="170px" height="83px"/>
<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/yuanmengjiankang.png" title="远盟健康" width="260px" height="83px"/>
<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/zhongkezhilian.png" title="中科智链" width="272px" height="83px"/>
<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/puqie_gaitubao_100x100.jpg" title="普切信息科技" width="83px" height="83px"/>&nbsp;&nbsp;
<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/known-users/tianbo-tech.png" title="杭州天铂云科" width="127px" height="70px"/>
![IFLYTEK](https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/iflytek.png)
&nbsp;&nbsp;<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/oneplus.png" title="一加" width="83px" height="83px"/>
&nbsp;&nbsp;<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/xiaomi.png" title="小米" width="170px" height="83px"/>
<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/yuanmengjiankang.png" title="远盟健康" width="260px" height="83px"/>
<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/zhongkezhilian.png" title="中科智链" width="272px" height="83px"/>
<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/puqie_gaitubao_100x100.jpg" title="普切信息科技" width="83px" height="83px"/>&nbsp;&nbsp;
<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/known-users/tianbo-tech.png" title="杭州天铂云科" width="127px" height="70px"/>
## Contact
愿意参与构建smart-doc或者是需要交流问题可以加入qq群
<img src="https://gitee.com/sunyurepository/smart-doc/raw/master/images/smart-doc-qq.png" title="qq群" width="200px" height="200px"/>
<img src="https://gitee.com/smart-doc-team/smart-doc/raw/master/images/smart-doc-qq.png" title="qq群" width="200px" height="200px"/>

View File

@ -79,7 +79,7 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
return null;
}
public boolean ignoreReturnObject(String typeName,List<String> ignoreParams) {
public boolean ignoreReturnObject(String typeName, List<String> ignoreParams) {
return false;
}
@ -131,7 +131,7 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
}
apiMethodDoc.setDeprecated(deprecated);
// build request params
List<ApiParam> requestParams = requestParams(method, DocTags.PARAM, projectBuilder);
List<ApiParam> requestParams = requestParams(method, projectBuilder);
apiMethodDoc.setRequestParams(requestParams);
// build response params
List<ApiParam> responseParams = buildReturnApiParams(method, projectBuilder);
@ -142,18 +142,17 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
return methodDocList;
}
private List<ApiParam> requestParams(final JavaMethod javaMethod, final String tagName, ProjectDocConfigBuilder builder) {
private List<ApiParam> requestParams(final JavaMethod javaMethod, ProjectDocConfigBuilder builder) {
boolean isStrict = builder.getApiConfig().isStrict();
boolean isShowJavaType = builder.getApiConfig().getShowJavaType();
Map<String, CustomRespField> responseFieldMap = new HashMap<>();
String className = javaMethod.getDeclaringClass().getCanonicalName();
Map<String, String> paramTagMap = DocUtil.getParamsComments(javaMethod, tagName, className);
Map<String, String> paramTagMap = DocUtil.getParamsComments(javaMethod, DocTags.PARAM, className);
List<JavaParameter> parameterList = javaMethod.getParameters();
if (parameterList.size() < 1) {
return null;
}
List<ApiParam> paramList = new ArrayList<>();
out:
for (JavaParameter parameter : parameterList) {
String paramName = parameter.getName();
String typeName = parameter.getType().getGenericCanonicalName();
@ -168,8 +167,6 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName);
List<JavaAnnotation> annotations = parameter.getAnnotations();
List<String> groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations);
String strRequired = "true";
Boolean required = Boolean.parseBoolean(strRequired);
if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) {
String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName);
String gicName = gicNameArr[0];
@ -183,28 +180,28 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
.setType(processedType);
paramList.add(param);
} else {
paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses,0));
paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0));
}
} else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) {
ApiParam param = ApiParam.of().setField(paramName)
.setType(JavaClassUtil.getClassSimpleName(typeName))
.setDesc(comment).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION);
.setDesc(comment).setRequired(true).setVersion(DocGlobalConstants.DEFAULT_VERSION);
paramList.add(param);
} else if (JavaClassValidateUtil.isMap(fullTypeName)) {
if (DocGlobalConstants.JAVA_MAP_FULLY.equals(typeName)) {
ApiParam apiParam = ApiParam.of().setField(paramName).setType(typeName)
.setDesc(comment).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION);
.setDesc(comment).setRequired(true).setVersion(DocGlobalConstants.DEFAULT_VERSION);
paramList.add(apiParam);
continue out;
continue;
}
String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName);
paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses,0));
paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0));
} else if (javaClass.isEnum()) {
ApiParam param = ApiParam.of().setField(paramName)
.setType("Enum").setDesc(comment).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION);
.setType("Enum").setDesc(comment).setRequired(true).setVersion(DocGlobalConstants.DEFAULT_VERSION);
paramList.add(param);
} else {
paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses,0));
paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0));
}
}
return paramList;
@ -272,8 +269,8 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc> {
returnClass = returnClass.replace(simpleReturn, JavaClassUtil.getClassSimpleName(simpleReturn));
String[] arrays = DocClassUtil.getSimpleGicName(returnClass);
for (String str : arrays) {
if(str.contains("[")){
str = str.substring(0,str.indexOf("["));
if (str.contains("[")) {
str = str.substring(0, str.indexOf("["));
}
String[] generics = str.split("<");
for (String generic : generics) {

View File

@ -129,8 +129,8 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
methodOrder++;
ApiMethodDoc apiMethodDoc = new ApiMethodDoc();
apiMethodDoc.setOrder(methodOrder);
apiMethodDoc.setDesc(method.getComment());
apiMethodDoc.setName(method.getName());
apiMethodDoc.setDesc(method.getComment());
String methodUid = DocUtil.generateId(clazName + method.getName());
apiMethodDoc.setMethodId(methodUid);
String apiNoteValue = DocUtil.getNormalTagComments(method, DocTags.API_NOTE, cls.getName());
@ -162,7 +162,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
apiMethodDoc.setPath(requestMapping.getShortUrl());
apiMethodDoc.setDeprecated(requestMapping.isDeprecated());
// build request params
List<ApiParam> requestParams = requestParams(method, DocTags.PARAM, projectBuilder);
List<ApiParam> requestParams = requestParams(method, projectBuilder);
if (paramsDataToTree) {
requestParams = ApiParamTreeUtil.apiParamToTree(requestParams);
}
@ -228,18 +228,13 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
String paramName = parameter.getName();
String typeName = javaType.getFullyQualifiedName();
String gicTypeName = javaType.getGenericCanonicalName();
String rewriteClassName = null;
String commentClass = paramsComments.get(paramName);
//ignore request params
if (Objects.nonNull(commentClass) && commentClass.contains(IGNORE)) {
continue;
}
if (Objects.nonNull(commentClass) && !DocGlobalConstants.NO_COMMENTS_FOUND.equals(commentClass)) {
String[] comments = commentClass.split("\\|");
rewriteClassName = comments[comments.length - 1];
} else {
rewriteClassName = replacementMap.get(typeName);
}
String rewriteClassName = this.getRewriteClassName(replacementMap, typeName, commentClass);
// rewrite class
if (DocUtil.isClassName(rewriteClassName)) {
gicTypeName = rewriteClassName;
@ -391,14 +386,14 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
String format = String.format(DocGlobalConstants.CURL_REQUEST_TYPE, methodType, header.toString(), url);
if (requestExample.isJson()) {
if (StringUtil.isNotEmpty(requestExample.getJsonBody())) {
exampleBody = String.format(DocGlobalConstants.CURL_POST_PUT_JSON, methodType,header.toString(), url,
exampleBody = String.format(DocGlobalConstants.CURL_POST_PUT_JSON, methodType, header.toString(), url,
requestExample.getJsonBody());
} else {
exampleBody = format;
}
} else {
if (StringUtil.isNotEmpty(body)) {
exampleBody = String.format(DocGlobalConstants.CURL_REQUEST_TYPE_DATA, methodType,header.toString(), url, body);
exampleBody = String.format(DocGlobalConstants.CURL_REQUEST_TYPE_DATA, methodType, header.toString(), url, body);
} else {
exampleBody = format;
}
@ -412,7 +407,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
url = StringUtil.removeQuotes(url);
url = apiMethodDoc.getServerUrl() + "/" + url;
url = UrlUtil.simplifyUrl(url);
exampleBody = String.format(DocGlobalConstants.CURL_REQUEST_TYPE, methodType,header.toString(), url);
exampleBody = String.format(DocGlobalConstants.CURL_REQUEST_TYPE, methodType, header.toString(), url);
requestExample.setExampleBody(exampleBody)
.setJsonBody(DocGlobalConstants.EMPTY)
.setUrl(url);
@ -420,13 +415,12 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
return requestExample;
}
private List<ApiParam> requestParams(final JavaMethod javaMethod, final String tagName, ProjectDocConfigBuilder builder) {
private List<ApiParam> requestParams(final JavaMethod javaMethod, ProjectDocConfigBuilder builder) {
boolean isStrict = builder.getApiConfig().isStrict();
Map<String, CustomRespField> responseFieldMap = new HashMap<>();
Map<String, String> replacementMap = builder.getReplaceClassMap();
String className = javaMethod.getDeclaringClass().getCanonicalName();
Map<String, String> paramTagMap = DocUtil.getParamsComments(javaMethod, tagName, className);
Map<String, String> replacementMap = builder.getReplaceClassMap();
Map<String, String> paramTagMap = DocUtil.getParamsComments(javaMethod, DocTags.PARAM, className);
List<JavaParameter> parameterList = javaMethod.getParameters();
if (parameterList.size() < 1) {
return null;
@ -441,21 +435,16 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
String typeName = parameter.getType().getGenericCanonicalName();
String simpleName = parameter.getType().getValue().toLowerCase();
String fullTypeName = parameter.getType().getFullyQualifiedName();
String rewriteClassName = null;
String commentClass = paramTagMap.get(paramName);
if (Objects.nonNull(commentClass) && !DocGlobalConstants.NO_COMMENTS_FOUND.equals(commentClass)) {
String[] comments = commentClass.split("\\|");
rewriteClassName = comments[comments.length - 1];
} else {
rewriteClassName = replacementMap.get(fullTypeName);
}
String rewriteClassName = getRewriteClassName(replacementMap, fullTypeName, commentClass);
// rewrite class
if (DocUtil.isClassName(rewriteClassName)) {
typeName = rewriteClassName;
fullTypeName = DocClassUtil.getSimpleName(rewriteClassName);
}
if (JavaClassValidateUtil.isMvcIgnoreParams(typeName, builder.getApiConfig().getIgnoreRequestParams())) {
continue out;
continue;
}
fullTypeName = DocClassUtil.rewriteRequestParam(fullTypeName);
typeName = DocClassUtil.rewriteRequestParam(typeName);
@ -473,7 +462,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
.setId(paramList.size() + 1)
.setDesc(comment).setRequired(true).setVersion(DocGlobalConstants.DEFAULT_VERSION);
paramList.add(param);
continue out;
continue;
}
JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName);
List<JavaAnnotation> annotations = parameter.getAnnotations();
@ -512,7 +501,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
requestBodyCounter++;
}
}
Boolean required = Boolean.parseBoolean(strRequired);
boolean required = Boolean.parseBoolean(strRequired);
if (isPathVariable) {
comment = comment + " (This is path param)";
}
@ -554,7 +543,7 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
.setPathParams(isPathVariable)
.setDesc(comment).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION);
paramList.add(apiParam);
continue out;
continue;
}
String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName);
paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], DocGlobalConstants.EMPTY, 0, "true", responseFieldMap, Boolean.FALSE, new HashMap<>(), builder, groupClasses, 0));
@ -605,4 +594,15 @@ public class SpringBootDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {
}
return false;
}
private String getRewriteClassName(Map<String, String> replacementMap, String fullTypeName, String commentClass) {
String rewriteClassName;
if (Objects.nonNull(commentClass) && !DocGlobalConstants.NO_COMMENTS_FOUND.equals(commentClass)) {
String[] comments = commentClass.split("\\|");
rewriteClassName = comments[comments.length - 1];
} else {
rewriteClassName = replacementMap.get(fullTypeName);
}
return rewriteClassName;
}
}