diff --git a/CHANGELOG.md b/CHANGELOG.md index 078cde6..50d2ccb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,13 @@ ## smart-doc版本 版本小于1.0都属于试用，正式1.0起始发布将会等到文中提到的问题解决后才发布。 #### 版本号：1.9.0 -- 更新日期: 2020-07-2x +- 更新日期: 2020-07-19 - 更新内容： - 1. 修改dubbo html依赖部分错乱问题 + 1. 修改dubbo html依赖部分错乱问题。 + 2. 新增自定义输出文件名称的配置。 + 3. 添加请求和响应示例的开关配置项。 + 4. 修改使用JSR303参数校验时，默认分组验证被忽略问题。 + 5. 修改jackson JsonIgnore注解在参数对象中不生效的问题。 #### 版本号：1.8.9 - 更新日期: 2020-07-05 - 更新内容： diff --git a/README.md b/README.md index dc7cb15..1ed0b14 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This example already provides a static html document generated in advance. You c Of course you can also browse `http://localhost:8080/doc/api.html`, which looks a html like generated by `asciidoctor-maven-plugin` plugin. ### Add Maven plugin -Add smart-doc-maven-plugin in your pom.xml. +Add [smart-doc-maven-plugin](https://github.com/smart-doc-group/smart-doc-maven-plugin) in your pom.xml. ``` com.github.shalousun @@ -92,6 +92,9 @@ When you need to use smart-doc to generate more API document information, you ca "inlineEnum":true,// Set to true to display enumeration details in the parameter table "recursionLimit":7,// Set the number of recursive executions to avoid stack overflow, the default is 7 "responseFieldToUnderline":true,//convert response field to underline + "allInOneDocFileName":"index.html",//Customize the output document name + "requestExample":"true",//Whether to display the request example in the document, the default value is true. + "responseExample":"true",//Whether to display the response example in the document, the default is true.   "dataDictionaries": [// Configure the data dictionary, no need to set     {       "title": "Order Status", // The name of the data dictionary @@ -217,6 +220,8 @@ Thanks to the following people who have submitted major pull requests: - [@caiqyxyx](https://gitee.com/cy-work) - [@lichoking](https://gitee.com/lichoking) - [@JtePromise](https://github.com/JtePromise) +- [@lizhen789](https://github.com/lizhen789) +- [@maliqiang](https://github.com/maliqiang) ## Other reference - [Smart-doc manual](https://github.com/shalousun/smart-doc/wiki) diff --git a/README_CN.md b/README_CN.md index b972410..66b612d 100644 --- a/README_CN.md +++ b/README_CN.md @@ -14,7 +14,7 @@ smart-doc完全基于接口源码分析来生成接口文档，完全做到零 - 对一些常用字段定义能够生成有效的模拟值。 - 支持生成json返回值示例。 - 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。 -- 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman json。 +- 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection。 - 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。 - 开放文档数据，可自由实现接入文档管理系统。 - 支持导出错误码和定义在代码中的各种字典码到接口文档。 @@ -27,7 +27,8 @@ smart-doc使用和测试可参考[smart-doc demo](https://gitee.com/sunyureposit ``` 你可以启动这个Spring Boot的项目，然后访问`http://localhost:8080/doc/api.html`来浏览smart-doc生成的接口文档。 ### Add Maven plugin -smart-doc官方目前已经开发完成maven 插件和gradle，你可以根据自己的构建工具来选择使用maven插件或者是gradle插件。 +smart-doc官方目前已经开发完成[maven插件](https://gitee.com/sunyurepository/smart-doc-maven-plugin) +和[gradle插件](https://gitee.com/sunyurepository/smart-doc-gradle-plugin)，你可以根据自己的构建工具来选择使用maven插件或者是gradle插件。 #### add plugin ``` @@ -90,6 +91,9 @@ smart-doc官方目前已经开发完成maven 插件和gradle，你可以根据 "responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始 "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始 "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since 1.8.8版本开始 + "allInOneDocFileName":"index.html",//自定义设置输出文档名称, @since 1.9.0 + "requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0 + "responseExample":"true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0 "dataDictionaries": [ //配置数据字典，没有需求可以不设置 { "title": "http状态码字典", //数据字典的名称 @@ -202,6 +206,8 @@ mvn clean install -Dmaven.test.skip=true - [@caiqyxyx](https://gitee.com/cy-work) - [@lichoking](https://gitee.com/lichoking) - [@JtePromise](https://github.com/JtePromise) +- [@lizhen789](https://github.com/lizhen789) +- [@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) diff --git a/pom.xml b/pom.xml index 48346ef..0445f94 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 smart-doc jar - 1.8.9 + 1.9.0 smart-doc https://github.com/shalousun/smart-doc.git @@ -32,7 +32,7 @@ UTF-8 - 0.61.32 + 0.62.2 @@ -44,7 +44,7 @@ com.ibeetl beetl - 3.1.6.RELEASE + 3.1.8.RELEASE com.thoughtworks.qdox @@ -55,6 +55,12 @@ com.github.javafaker javafaker 1.0.2 + + + commons-lang3 + org.apache.commons + + com.github.shalousun diff --git a/src/main/java/com/power/doc/builder/DocBuilderTemplate.java b/src/main/java/com/power/doc/builder/DocBuilderTemplate.java index 58cab10..ffa9e7a 100644 --- a/src/main/java/com/power/doc/builder/DocBuilderTemplate.java +++ b/src/main/java/com/power/doc/builder/DocBuilderTemplate.java @@ -106,6 +106,8 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate { tpl.binding(TemplateVariable.VERSION.getVariable(), now); tpl.binding(TemplateVariable.CREATE_TIME.getVariable(), strTime); tpl.binding(TemplateVariable.PROJECT_NAME.getVariable(), config.getProjectName()); + tpl.binding(TemplateVariable.REQUEST_EXAMPLE.getVariable(), config.isRequestExample()); + tpl.binding(TemplateVariable.RESPONSE_EXAMPLE.getVariable(), config.isResponseExample()); if (CollectionUtil.isEmpty(errorCodeList)) { tpl.binding(TemplateVariable.DICT_ORDER.getVariable(), apiDocList.size() + 1); } else { diff --git a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java index a116355..fb43791 100644 --- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java @@ -37,6 +37,7 @@ import com.power.doc.template.SpringBootDocBuildTemplate; import com.power.doc.utils.BeetlTemplateUtil; import com.power.doc.utils.MarkDownUtil; import com.thoughtworks.qdox.JavaProjectBuilder; +import org.apache.commons.lang3.StringUtils; import org.beetl.core.Template; import java.util.List; @@ -79,6 +80,9 @@ public class HtmlApiDocBuilder { if (config.isAllInOne()) { Template indexCssTemplate = BeetlTemplateUtil.getByName(ALL_IN_ONE_CSS); FileUtil.nioWriteFile(indexCssTemplate.render(), config.getOutPath() + FILE_SEPARATOR + ALL_IN_ONE_CSS); + if(StringUtils.isNotEmpty(config.getAllInOneDocFileName())){ + INDEX_HTML = config.getAllInOneDocFileName(); + } builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_HTML_TPL, INDEX_HTML); } else { List apiDocDictList = builderTemplate.buildDictionary(config, javaProjectBuilder); diff --git a/src/main/java/com/power/doc/constants/DocAnnotationConstants.java b/src/main/java/com/power/doc/constants/DocAnnotationConstants.java index 02e50b3..0a2cdd1 100644 --- a/src/main/java/com/power/doc/constants/DocAnnotationConstants.java +++ b/src/main/java/com/power/doc/constants/DocAnnotationConstants.java @@ -1,37 +1,39 @@ -package com.power.doc.constants; - -/** - * java annotations - * - * @author yu 2019/9/19. - */ -public interface DocAnnotationConstants { - - String SHORT_CONTROLLER = "Controller"; - - String SHORT_REST_CONTROLLER = "RestController"; - - String SHORT_PATH_VARIABLE = "PathVariable"; - - String SHORT_REQ_PARAM = "RequestParam"; - - String SHORT_JSON_IGNORE = "JsonIgnore"; - - String SHORT_JSON_PROPERTY = "JsonProperty"; - - String SHORT_JSON_FIELD = "JSONField"; - - String REQUIRED_PROP = "required"; - - String SERIALIZE_PROP = "serialize"; - - String NAME_PROP = "name"; - - String VALUE_PROP = "value"; - - String GROUP_PROP = "groups"; - - String DEFAULT_VALUE_PROP = "defaultValue"; - - String REQUEST_MAPPING = "RequestMapping"; -} +package com.power.doc.constants; + +/** + * java annotations + * + * @author yu 2019/9/19. + */ +public interface DocAnnotationConstants { + + String SHORT_CONTROLLER = "Controller"; + + String SHORT_REST_CONTROLLER = "RestController"; + + String SHORT_PATH_VARIABLE = "PathVariable"; + + String SHORT_REQ_PARAM = "RequestParam"; + + String SHORT_JSON_IGNORE = "JsonIgnore"; + + String SHORT_JSON_PROPERTY = "JsonProperty"; + + String SHORT_JSON_FIELD = "JSONField"; + + String REQUIRED_PROP = "required"; + + String SERIALIZE_PROP = "serialize"; + + String NAME_PROP = "name"; + + String VALUE_PROP = "value"; + + String GROUP_PROP = "groups"; + + String DEFAULT_VALUE_PROP = "defaultValue"; + + String REQUEST_MAPPING = "RequestMapping"; + + String DEPRECATED = "Deprecated"; +} diff --git a/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java b/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java index 7dbc13b..58e13f1 100644 --- a/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java +++ b/src/main/java/com/power/doc/constants/DubboAnnotationConstants.java @@ -1,9 +1,15 @@ -package com.power.doc.constants; - -/** - * dubbo annotation - * @author yu 2020/1/29. - */ -public interface DubboAnnotationConstants { - String SERVICE = "org.apache.dubbo.config.annotation.Service"; -} +package com.power.doc.constants; + +/** + * dubbo annotation + * @author yu 2020/1/29. + */ +public interface DubboAnnotationConstants { + + String SERVICE = "org.apache.dubbo.config.annotation.Service"; + + /** + * @since dubbo 2.7.7 + */ + String DUBBO_SERVICE = "org.apache.dubbo.config.annotation.DubboService"; +} diff --git a/src/main/java/com/power/doc/constants/TemplateVariable.java b/src/main/java/com/power/doc/constants/TemplateVariable.java index e391b86..8f60654 100644 --- a/src/main/java/com/power/doc/constants/TemplateVariable.java +++ b/src/main/java/com/power/doc/constants/TemplateVariable.java @@ -1,62 +1,62 @@ -/* - * smart-doc https://github.com/shalousun/smart-doc - * - * Copyright (C) 2018-2020 smart-doc - * - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -package com.power.doc.constants; - -/** - * @author yu 2019/9/21. - */ -public enum TemplateVariable { - DESC("desc"), - NAME("name"), - LIST("list"), - API_DOC_LIST("apiDocList"), - ERROR_CODE_LIST("errorCodeList"), - VERSION_LIST("revisionLogList"), - DEPENDENCY_LIST("dependencyList"), - HOME_PAGE("homePage"), - HTML("html"), - TITLE("title"), - ERROR_LIST_TITLE("errorListTitle"), - CREATE_TIME("createTime"), - PROJECT_NAME("projectName"), - DICT_LIST("dictList"), - DICT_LIST_TITLE("dictListTitle"), - DICT_ORDER("dictListOrder"), - VERSION("version"), - PROTOCOL("protocol"), - AUTHOR("author"), - URI("uri"), - RPC_CONSUMER_CONFIG("consumerConfigExample") - ; - - - private String variable; - - TemplateVariable(String variable) { - this.variable = variable; - } - - public String getVariable() { - return this.variable; - } -} +/* + * smart-doc https://github.com/shalousun/smart-doc + * + * Copyright (C) 2018-2020 smart-doc + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package com.power.doc.constants; + +/** + * @author yu 2019/9/21. + */ +public enum TemplateVariable { + DESC("desc"), + NAME("name"), + LIST("list"), + API_DOC_LIST("apiDocList"), + ERROR_CODE_LIST("errorCodeList"), + VERSION_LIST("revisionLogList"), + DEPENDENCY_LIST("dependencyList"), + HOME_PAGE("homePage"), + HTML("html"), + TITLE("title"), + ERROR_LIST_TITLE("errorListTitle"), + CREATE_TIME("createTime"), + PROJECT_NAME("projectName"), + DICT_LIST("dictList"), + DICT_LIST_TITLE("dictListTitle"), + DICT_ORDER("dictListOrder"), + VERSION("version"), + PROTOCOL("protocol"), + AUTHOR("author"), + URI("uri"), + RPC_CONSUMER_CONFIG("consumerConfigExample"), + REQUEST_EXAMPLE("isRequestExample"), + RESPONSE_EXAMPLE("isResponseExample"); + + private String variable; + + TemplateVariable(String variable) { + this.variable = variable; + } + + public String getVariable() { + return this.variable; + } +} diff --git a/src/main/java/com/power/doc/handler/SpringMVCRequestMappingHandler.java b/src/main/java/com/power/doc/handler/SpringMVCRequestMappingHandler.java index 66a9bc7..363d467 100644 --- a/src/main/java/com/power/doc/handler/SpringMVCRequestMappingHandler.java +++ b/src/main/java/com/power/doc/handler/SpringMVCRequestMappingHandler.java @@ -24,6 +24,7 @@ package com.power.doc.handler; import com.power.common.util.StringUtil; import com.power.common.util.UrlUtil; +import com.power.doc.constants.DocAnnotationConstants; import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.Methods; import com.power.doc.constants.SpringMvcAnnotations; @@ -67,7 +68,7 @@ public class SpringMVCRequestMappingHandler { if (produces != null) { mediaType = produces.toString(); } - if ("Deprecated".equals(annotationName)) { + if (DocAnnotationConstants.DEPRECATED.equals(annotationName)) { deprecated = true; } if (SpringMvcAnnotations.REQUEST_MAPPING.equals(annotationName) || DocGlobalConstants.REQUEST_MAPPING_FULLY.equals(annotationName)) { diff --git a/src/main/java/com/power/doc/helper/JsonBuildHelper.java b/src/main/java/com/power/doc/helper/JsonBuildHelper.java index 411fc4d..3438051 100644 --- a/src/main/java/com/power/doc/helper/JsonBuildHelper.java +++ b/src/main/java/com/power/doc/helper/JsonBuildHelper.java @@ -75,10 +75,7 @@ public class JsonBuildHelper { boolean isResp, int counter, Map registryClasses, ProjectDocConfigBuilder builder) { //存储泛型所对应的实体类 - Map genericMap = new HashMap<>(10); - - - + Map genericMap = new HashMap<>(10); JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(typeName); ApiConfig apiConfig = builder.getApiConfig(); if (counter > apiConfig.getRecursionLimit()) { @@ -107,14 +104,13 @@ public class JsonBuildHelper { JavaClass cls = builder.getClassByName(typeName); - data0.append("{"); String[] globGicName = DocClassUtil.getSimpleGicName(genericCanonicalName); //添加泛型对应关系 - if(cls!=null && null != cls.getTypeParameters()){ + if (cls != null && null != cls.getTypeParameters()) { List> variables = cls.getTypeParameters(); - for(int i=0;i annotations = docField.getAnnotations(); for (JavaAnnotation annotation : annotations) { String annotationName = annotation.getType().getValue(); - if (DocAnnotationConstants.SHORT_JSON_IGNORE.equals(annotationName) && isResp) { + if (DocAnnotationConstants.SHORT_JSON_IGNORE.equals(annotationName)) { continue out; - } else if (DocAnnotationConstants.SHORT_JSON_FIELD.equals(annotationName) && isResp) { + } else if (DocAnnotationConstants.SHORT_JSON_FIELD.equals(annotationName)) { if (null != annotation.getProperty(DocAnnotationConstants.SERIALIZE_PROP)) { if (Boolean.FALSE.toString().equals(annotation.getProperty(DocAnnotationConstants.SERIALIZE_PROP).toString())) { continue out; @@ -210,7 +206,7 @@ public class JsonBuildHelper { } else if (null != annotation.getProperty(DocAnnotationConstants.NAME_PROP)) { fieldName = StringUtil.removeQuotes(annotation.getProperty(DocAnnotationConstants.NAME_PROP).toString()); } - } else if (DocAnnotationConstants.SHORT_JSON_PROPERTY.equals(annotationName) && isResp) { + } else if (DocAnnotationConstants.SHORT_JSON_PROPERTY.equals(annotationName)) { if (null != annotation.getProperty(DocAnnotationConstants.VALUE_PROP)) { fieldName = StringUtil.removeQuotes(annotation.getProperty(DocAnnotationConstants.VALUE_PROP).toString()); } @@ -267,7 +263,7 @@ public class JsonBuildHelper { data0.append("{\"object\":\"any object\"},"); continue out; } - String gicName1 = genericMap.get(gicName)==null ? globGicName[0] : genericMap.get(gicName); + String gicName1 = genericMap.get(gicName) == null ? globGicName[0] : genericMap.get(gicName); if (DocGlobalConstants.JAVA_STRING_FULLY.equals(gicName1)) { data0.append("[").append("\"").append(buildJson(gicName1, gicName1, isResp, nextLevel, registryClasses, builder)).append("\"]").append(","); } else { @@ -295,7 +291,7 @@ public class JsonBuildHelper { } String gicName = fieldGicName.substring(fieldGicName.indexOf(",") + 1, fieldGicName.indexOf(">")); if (gicName.length() == 1) { - String gicName1 = genericMap.get(gicName)==null ? globGicName[0] : genericMap.get(gicName); + String gicName1 = genericMap.get(gicName) == null ? globGicName[0] : genericMap.get(gicName); if (DocGlobalConstants.JAVA_STRING_FULLY.equals(gicName1)) { data0.append("{").append("\"mapKey\":\"").append(buildJson(gicName1, gicName1, isResp, nextLevel, registryClasses, builder)).append("\"},"); } else { @@ -310,7 +306,7 @@ public class JsonBuildHelper { } } else if (subTypeName.length() == 1) { if (!typeName.equals(genericCanonicalName)) { - String gicName = genericMap.get(subTypeName)==null ? globGicName[0] : genericMap.get(subTypeName); + String gicName = genericMap.get(subTypeName) == null ? globGicName[0] : genericMap.get(subTypeName); if (JavaClassValidateUtil.isPrimitive(gicName)) { data0.append(DocUtil.jsonValueByType(gicName)).append(","); } else { @@ -323,8 +319,8 @@ public class JsonBuildHelper { } else if (DocGlobalConstants.JAVA_OBJECT_FULLY.equals(subTypeName)) { if (isGenerics) { data0.append("{\"object\":\"any object\"},"); - } else if ( globGicName.length > 0) { - String gicName = genericMap.get(subTypeName)==null ? globGicName[0] : genericMap.get(subTypeName); + } else if (globGicName.length > 0) { + String gicName = genericMap.get(subTypeName) == null ? globGicName[0] : genericMap.get(subTypeName); if (!typeName.equals(genericCanonicalName)) { if (JavaClassValidateUtil.isPrimitive(gicName)) { data0.append("\"").append(buildJson(gicName, genericCanonicalName, isResp, nextLevel, registryClasses, builder)).append("\","); diff --git a/src/main/java/com/power/doc/model/ApiConfig.java b/src/main/java/com/power/doc/model/ApiConfig.java index b5c1062..f125174 100644 --- a/src/main/java/com/power/doc/model/ApiConfig.java +++ b/src/main/java/com/power/doc/model/ApiConfig.java @@ -1,451 +1,496 @@ -/* - * smart-doc - * - * Copyright (C) 2018-2020 smart-doc - * - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. - */ -package com.power.doc.model; - -import com.power.common.util.CollectionUtil; -import com.power.doc.constants.DocLanguage; -import com.power.doc.model.rpc.RpcApiDependency; - -import java.util.List; -import java.util.stream.Collectors; - -/** - * Description: - * api config info - * - * @author yu 2018/06/18. - */ -public class ApiConfig { - - /** - * Web server base url - */ - private String serverUrl; - - /** - * Set comments check mode - */ - private boolean isStrict; - - /** - * Merge all api doc into one document - */ - private boolean allInOne; - - /** - * output path - */ - private String outPath; - - - /** - * source path - */ - private List sourceCodePaths; - - /** - * list of Request headers - */ - private List requestHeaders; - - /** - * @since 1.7.5 - * cover old all in one markdown - */ - private boolean coverOld; - - /** - * list of custom response filed - */ - private List customResponseFields; - - /** - * List of error code - * - * @return - */ - - private List errorCodes; - - /** - * controller package filters - */ - private String packageFilters; - - /** - * List of change log - */ - private List revisionLogs; - - /** - * @since 1.7+ - */ - private boolean md5EncryptedHtmlName; - - /** - * language support - * - * @since 1.7+ - */ - private DocLanguage language; - - /** - * adoc flag - */ - private boolean adoc; - - - /** - * api data dictionary - */ - private List dataDictionaries; - - /** - * @since 1.7.9 - * api error code dictionary - */ - private List errorCodeDictionaries; - - /** - * list of custom response filed - */ - private List apiObjectReplacements; - - /** - * list of rpc api dependencies - */ - private List rpcApiDependencies; - - /** - * list of api constant - */ - private List apiConstants; - - /** - * @since 1.7.5 - * project name - */ - private String projectName; - - /** - * Skip Transient Field - */ - private boolean skipTransientField = true; - - /** - * @since 1.7.10 - * default show author - */ - private boolean showAuthor = true; - - /** - * convert request field to underline - * - * @since 1.8.7 - */ - private boolean requestFieldToUnderline; - - /** - * convert response field to underline - * - * @since 1.8.7 - */ - private boolean responseFieldToUnderline; - - /** - * sort by title - * - * @since 1.8.7 - */ - private boolean sortByTitle; - - /** - * is rest api doc - * - * @since 1.8.7 - */ - private Boolean showJavaType = Boolean.FALSE; - - /** - * is inline enum field comment - * @since 1.8.8 - */ - private Boolean inlineEnum = Boolean.FALSE; - - /** - * rpc consumer config example - * @since 1.8.7 - */ - private String rpcConsumerConfig; - - /** - * recursion limit - * @since 1.8.8 - */ - private int recursionLimit = 7; - - - public String getServerUrl() { - return serverUrl; - } - - public void setServerUrl(String serverUrl) { - this.serverUrl = serverUrl; - } - - public boolean isStrict() { - return isStrict; - } - - public void setStrict(boolean strict) { - isStrict = strict; - } - - public String getOutPath() { - return outPath; - } - - public void setOutPath(String outPath) { - this.outPath = outPath; - } - - public List getRequestHeaders() { - return requestHeaders; - } - - public void setRequestHeaders(ApiReqHeader... requestHeaders) { - this.requestHeaders = CollectionUtil.asList(requestHeaders); - this.requestHeaders.stream().map(header -> header.setDesc(header.getDesc() + "(Global)")) - .collect(Collectors.toList()); - } - - public List getCustomResponseFields() { - return customResponseFields; - } - - public void setCustomResponseFields(CustomRespField... customResponseFields) { - this.customResponseFields = CollectionUtil.asList(customResponseFields); - } - - - public List getErrorCodes() { - return errorCodes; - } - - public void setErrorCodes(List errorCodes) { - this.errorCodes = errorCodes; - } - - public List getSourceCodePaths() { - return sourceCodePaths; - } - - public void setSourceCodePaths(SourceCodePath... sourcePaths) { - this.sourceCodePaths = CollectionUtil.asList(sourcePaths); - } - - public boolean isAllInOne() { - return allInOne; - } - - public void setAllInOne(boolean allInOne) { - this.allInOne = allInOne; - } - - public String getPackageFilters() { - return packageFilters; - } - - public void setPackageFilters(String packageFilters) { - this.packageFilters = packageFilters; - } - - public List getRevisionLogs() { - return revisionLogs; - } - - public void setRevisionLogs(RevisionLog... revisionLogs) { - this.revisionLogs = CollectionUtil.asList(revisionLogs); - } - - - public boolean isMd5EncryptedHtmlName() { - return md5EncryptedHtmlName; - } - - public void setMd5EncryptedHtmlName(boolean md5EncryptedHtmlName) { - this.md5EncryptedHtmlName = md5EncryptedHtmlName; - } - - public DocLanguage getLanguage() { - return language; - } - - public void setLanguage(DocLanguage language) { - this.language = language; - } - - public boolean isAdoc() { - return adoc; - } - - public void setAdoc(boolean adoc) { - this.adoc = adoc; - } - - public List getDataDictionaries() { - return dataDictionaries; - } - - public void setDataDictionaries(ApiDataDictionary... dataDictConfigs) { - this.dataDictionaries = CollectionUtil.asList(dataDictConfigs); - } - - public ApiDataDictionary getDataDictionary(String enumClassSimpleName) { - return this.dataDictionaries.stream().filter((apiDataDictionary -> - enumClassSimpleName.equalsIgnoreCase(apiDataDictionary.getEnumClassName()))) - .findFirst().orElse(new ApiDataDictionary()); - } - - public List getErrorCodeDictionaries() { - return errorCodeDictionaries; - } - - public void setErrorCodeDictionaries(ApiErrorCodeDictionary... errorCodeDictConfigs) { - this.errorCodeDictionaries = CollectionUtil.asList(errorCodeDictConfigs); - } - - public List getApiObjectReplacements() { - return apiObjectReplacements; - } - - public void setApiObjectReplacements(ApiObjectReplacement... apiObjectReplaces) { - this.apiObjectReplacements = CollectionUtil.asList(apiObjectReplaces); - } - - public List getRpcApiDependencies() { - return rpcApiDependencies; - } - - public void setRpcApiDependencies(RpcApiDependency... rpcApiDependencies) { - this.rpcApiDependencies = CollectionUtil.asList(rpcApiDependencies); - } - - public List getApiConstants() { - return apiConstants; - } - - public void setApiConstants(ApiConstant... apiConstants) { - this.apiConstants = CollectionUtil.asList(apiConstants); - } - - public boolean isCoverOld() { - return coverOld; - } - - public void setCoverOld(boolean coverOld) { - this.coverOld = coverOld; - } - - public String getProjectName() { - return projectName; - } - - public void setProjectName(String projectName) { - this.projectName = projectName; - } - - public boolean isSkipTransientField() { - return skipTransientField; - } - - public void setSkipTransientField(boolean skipTransientField) { - this.skipTransientField = skipTransientField; - } - - public boolean isShowAuthor() { - return showAuthor; - } - - public void setShowAuthor(boolean showAuthor) { - this.showAuthor = showAuthor; - } - - public boolean isRequestFieldToUnderline() { - return requestFieldToUnderline; - } - - public void setRequestFieldToUnderline(boolean requestFieldToUnderline) { - this.requestFieldToUnderline = requestFieldToUnderline; - } - - public boolean isResponseFieldToUnderline() { - return responseFieldToUnderline; - } - - public void setResponseFieldToUnderline(boolean responseFieldToUnderline) { - this.responseFieldToUnderline = responseFieldToUnderline; - } - - public boolean isSortByTitle() { - return sortByTitle; - } - - public void setSortByTitle(boolean sortByTitle) { - this.sortByTitle = sortByTitle; - } - - public Boolean getShowJavaType() { - return showJavaType; - } - - public void setShowJavaType(Boolean showJavaType) { - this.showJavaType = showJavaType; - } - - public String getRpcConsumerConfig() { - return rpcConsumerConfig; - } - - public void setRpcConsumerConfig(String rpcConsumerConfig) { - this.rpcConsumerConfig = rpcConsumerConfig; - } - - public Boolean getInlineEnum() { - return inlineEnum; - } - - public void setInlineEnum(Boolean inlineEnum) { - this.inlineEnum = inlineEnum; - } - - public int getRecursionLimit() { - return recursionLimit; - } - - public void setRecursionLimit(int recursionLimit) { - this.recursionLimit = recursionLimit; - } - - -} +/* + * smart-doc + * + * Copyright (C) 2018-2020 smart-doc + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package com.power.doc.model; + +import com.power.common.util.CollectionUtil; +import com.power.doc.constants.DocLanguage; +import com.power.doc.model.rpc.RpcApiDependency; + +import java.util.List; +import java.util.stream.Collectors; + +/** + * Description: + * api config info + * + * @author yu 2018/06/18. + */ +public class ApiConfig { + + /** + * Web server base url + */ + private String serverUrl; + + /** + * Set comments check mode + */ + private boolean isStrict; + + /** + * Merge all api doc into one document + */ + private boolean allInOne; + + /** + * output path + */ + private String outPath; + + + /** + * source path + */ + private List sourceCodePaths; + + /** + * list of Request headers + */ + private List requestHeaders; + + /** + * @since 1.7.5 + * cover old all in one markdown + */ + private boolean coverOld; + + /** + * list of custom response filed + */ + private List customResponseFields; + + /** + * List of error code + * + * @return + */ + + private List errorCodes; + + /** + * controller package filters + */ + private String packageFilters; + + /** + * List of change log + */ + private List revisionLogs; + + /** + * @since 1.7+ + */ + private boolean md5EncryptedHtmlName; + + /** + * language support + * + * @since 1.7+ + */ + private DocLanguage language; + + /** + * adoc flag + */ + private boolean adoc; + + + /** + * api data dictionary + */ + private List dataDictionaries; + + /** + * @since 1.7.9 + * api error code dictionary + */ + private List errorCodeDictionaries; + + /** + * list of custom response filed + */ + private List apiObjectReplacements; + + /** + * list of rpc api dependencies + */ + private List rpcApiDependencies; + + /** + * list of api constant + */ + private List apiConstants; + + /** + * @since 1.7.5 + * project name + */ + private String projectName; + + /** + * Skip Transient Field + */ + private boolean skipTransientField = true; + + /** + * @since 1.7.10 + * default show author + */ + private boolean showAuthor = true; + + /** + * convert request field to underline + * + * @since 1.8.7 + */ + private boolean requestFieldToUnderline; + + /** + * convert response field to underline + * + * @since 1.8.7 + */ + private boolean responseFieldToUnderline; + + /** + * sort by title + * + * @since 1.8.7 + */ + private boolean sortByTitle; + + /** + * is rest api doc + * + * @since 1.8.7 + */ + private Boolean showJavaType = Boolean.FALSE; + + /** + * is inline enum field comment + * + * @since 1.8.8 + */ + private Boolean inlineEnum = Boolean.FALSE; + + /** + * rpc consumer config example + * + * @since 1.8.7 + */ + private String rpcConsumerConfig; + + /** + * recursion limit + * + * @since 1.8.8 + */ + private int recursionLimit = 7; + + /** + * request example + * + * @since 1.9.0 + */ + private boolean requestExample = Boolean.TRUE; + + /** + * response example + * + * @since 1.9.0 + */ + private boolean responseExample = Boolean.TRUE; + + /** + * custom setting api document name + * @since 1.9.0 + */ + private String allInOneDocFileName; + + + public String getServerUrl() { + return serverUrl; + } + + public void setServerUrl(String serverUrl) { + this.serverUrl = serverUrl; + } + + public boolean isStrict() { + return isStrict; + } + + public void setStrict(boolean strict) { + isStrict = strict; + } + + public String getOutPath() { + return outPath; + } + + public void setOutPath(String outPath) { + this.outPath = outPath; + } + + public List getRequestHeaders() { + return requestHeaders; + } + + public void setRequestHeaders(ApiReqHeader... requestHeaders) { + this.requestHeaders = CollectionUtil.asList(requestHeaders); + this.requestHeaders.stream().map(header -> header.setDesc(header.getDesc() + "(Global)")) + .collect(Collectors.toList()); + } + + public List getCustomResponseFields() { + return customResponseFields; + } + + public void setCustomResponseFields(CustomRespField... customResponseFields) { + this.customResponseFields = CollectionUtil.asList(customResponseFields); + } + + + public List getErrorCodes() { + return errorCodes; + } + + public void setErrorCodes(List errorCodes) { + this.errorCodes = errorCodes; + } + + public List getSourceCodePaths() { + return sourceCodePaths; + } + + public void setSourceCodePaths(SourceCodePath... sourcePaths) { + this.sourceCodePaths = CollectionUtil.asList(sourcePaths); + } + + public boolean isAllInOne() { + return allInOne; + } + + public void setAllInOne(boolean allInOne) { + this.allInOne = allInOne; + } + + public String getPackageFilters() { + return packageFilters; + } + + public void setPackageFilters(String packageFilters) { + this.packageFilters = packageFilters; + } + + public List getRevisionLogs() { + return revisionLogs; + } + + public void setRevisionLogs(RevisionLog... revisionLogs) { + this.revisionLogs = CollectionUtil.asList(revisionLogs); + } + + + public boolean isMd5EncryptedHtmlName() { + return md5EncryptedHtmlName; + } + + public void setMd5EncryptedHtmlName(boolean md5EncryptedHtmlName) { + this.md5EncryptedHtmlName = md5EncryptedHtmlName; + } + + public DocLanguage getLanguage() { + return language; + } + + public void setLanguage(DocLanguage language) { + this.language = language; + } + + public boolean isAdoc() { + return adoc; + } + + public void setAdoc(boolean adoc) { + this.adoc = adoc; + } + + public List getDataDictionaries() { + return dataDictionaries; + } + + public void setDataDictionaries(ApiDataDictionary... dataDictConfigs) { + this.dataDictionaries = CollectionUtil.asList(dataDictConfigs); + } + + public ApiDataDictionary getDataDictionary(String enumClassSimpleName) { + return this.dataDictionaries.stream().filter((apiDataDictionary -> + enumClassSimpleName.equalsIgnoreCase(apiDataDictionary.getEnumClassName()))) + .findFirst().orElse(new ApiDataDictionary()); + } + + public List getErrorCodeDictionaries() { + return errorCodeDictionaries; + } + + public void setErrorCodeDictionaries(ApiErrorCodeDictionary... errorCodeDictConfigs) { + this.errorCodeDictionaries = CollectionUtil.asList(errorCodeDictConfigs); + } + + public List getApiObjectReplacements() { + return apiObjectReplacements; + } + + public void setApiObjectReplacements(ApiObjectReplacement... apiObjectReplaces) { + this.apiObjectReplacements = CollectionUtil.asList(apiObjectReplaces); + } + + public List getRpcApiDependencies() { + return rpcApiDependencies; + } + + public void setRpcApiDependencies(RpcApiDependency... rpcApiDependencies) { + this.rpcApiDependencies = CollectionUtil.asList(rpcApiDependencies); + } + + public List getApiConstants() { + return apiConstants; + } + + public void setApiConstants(ApiConstant... apiConstants) { + this.apiConstants = CollectionUtil.asList(apiConstants); + } + + public boolean isCoverOld() { + return coverOld; + } + + public void setCoverOld(boolean coverOld) { + this.coverOld = coverOld; + } + + public String getProjectName() { + return projectName; + } + + public void setProjectName(String projectName) { + this.projectName = projectName; + } + + public boolean isSkipTransientField() { + return skipTransientField; + } + + public void setSkipTransientField(boolean skipTransientField) { + this.skipTransientField = skipTransientField; + } + + public boolean isShowAuthor() { + return showAuthor; + } + + public void setShowAuthor(boolean showAuthor) { + this.showAuthor = showAuthor; + } + + public boolean isRequestFieldToUnderline() { + return requestFieldToUnderline; + } + + public void setRequestFieldToUnderline(boolean requestFieldToUnderline) { + this.requestFieldToUnderline = requestFieldToUnderline; + } + + public boolean isResponseFieldToUnderline() { + return responseFieldToUnderline; + } + + public void setResponseFieldToUnderline(boolean responseFieldToUnderline) { + this.responseFieldToUnderline = responseFieldToUnderline; + } + + public boolean isSortByTitle() { + return sortByTitle; + } + + public void setSortByTitle(boolean sortByTitle) { + this.sortByTitle = sortByTitle; + } + + public Boolean getShowJavaType() { + return showJavaType; + } + + public void setShowJavaType(Boolean showJavaType) { + this.showJavaType = showJavaType; + } + + public String getRpcConsumerConfig() { + return rpcConsumerConfig; + } + + public void setRpcConsumerConfig(String rpcConsumerConfig) { + this.rpcConsumerConfig = rpcConsumerConfig; + } + + public Boolean getInlineEnum() { + return inlineEnum; + } + + public void setInlineEnum(Boolean inlineEnum) { + this.inlineEnum = inlineEnum; + } + + public int getRecursionLimit() { + return recursionLimit; + } + + public void setRecursionLimit(int recursionLimit) { + this.recursionLimit = recursionLimit; + } + + public boolean isRequestExample() { + return requestExample; + } + + public void setRequestExample(boolean requestExample) { + this.requestExample = requestExample; + } + + public boolean isResponseExample() { + return responseExample; + } + + public void setResponseExample(boolean responseExample) { + this.responseExample = responseExample; + } + + public String getAllInOneDocFileName() { + return allInOneDocFileName; + } + + public void setAllInOneDocFileName(String allInOneDocFileName) { + this.allInOneDocFileName = allInOneDocFileName; + } +} \ No newline at end of file diff --git a/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java b/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java index 79f112b..f4678e8 100644 --- a/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java +++ b/src/main/java/com/power/doc/template/RpcDocBuildTemplate.java @@ -24,6 +24,7 @@ package com.power.doc.template; import com.power.common.util.StringUtil; import com.power.doc.builder.ProjectDocConfigBuilder; +import com.power.doc.constants.DocAnnotationConstants; import com.power.doc.constants.DocGlobalConstants; import com.power.doc.constants.DocTags; import com.power.doc.constants.DubboAnnotationConstants; @@ -99,7 +100,7 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { List annotations = method.getAnnotations(); for (JavaAnnotation annotation : annotations) { String annotationName = annotation.getType().getName(); - if ("Deprecated".equals(annotationName)) { + if (DocAnnotationConstants.DEPRECATED.equals(annotationName)) { deprecated = true; } } @@ -213,7 +214,7 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { List classAnnotations = cls.getAnnotations(); for (JavaAnnotation annotation : classAnnotations) { String name = annotation.getType().getCanonicalName(); - if (DubboAnnotationConstants.SERVICE.equals(name)) { + if (DubboAnnotationConstants.SERVICE.equals(name) || DubboAnnotationConstants.DUBBO_SERVICE.equals(name)) { return true; } } @@ -227,7 +228,8 @@ public class RpcDocBuildTemplate implements IDocBuildTemplate { return false; } - private void handleJavaApiDoc(JavaClass cls, List apiDocList, List apiMethodDocs, int order, ProjectDocConfigBuilder builder) { + private void handleJavaApiDoc(JavaClass cls, List apiDocList, List apiMethodDocs, + int order, ProjectDocConfigBuilder builder) { String className = cls.getCanonicalName(); List javaTypes = cls.getImplements(); if (javaTypes.size() >= 1 && !cls.isInterface()) { diff --git a/src/main/java/com/power/doc/utils/JavaClassUtil.java b/src/main/java/com/power/doc/utils/JavaClassUtil.java index daf96aa..4faa86d 100644 --- a/src/main/java/com/power/doc/utils/JavaClassUtil.java +++ b/src/main/java/com/power/doc/utils/JavaClassUtil.java @@ -266,6 +266,11 @@ public class JavaClassUtil { List validates = DocValidatorAnnotationEnum.listValidatorAnnotations(); List annotationValueList = getAnnotationValues(validates, javaAnnotation); addGroupClass(annotationValueList, javaClassList); + String simpleAnnotationName = javaAnnotation.getType().getValue(); + // add default group + if (javaClassList.size() == 0 && JavaClassValidateUtil.isJSR303Required(simpleAnnotationName)) { + javaClassList.add("javax.validation.groups.Default"); + } return javaClassList; } @@ -305,6 +310,7 @@ public class JavaClassUtil { /** * Get Map of final field and value + * * @param clazz Java class * @return Map * @throws IllegalAccessException IllegalAccessException diff --git a/src/main/resources/default.json b/src/main/resources/default.json index be9fd5f..f0ecc90 100644 --- a/src/main/resources/default.json +++ b/src/main/resources/default.json @@ -4,10 +4,13 @@ "allInOne": true, "outPath": "D://md2", "coverOld": true, + "allInOneDocFileName":"demoProject.html", "packageFilters": "", "md5EncryptedHtmlName": false, "projectName": "smart-doc", "skipTransientField": true, + "requestExample": true, + "responseExample": true, "revisionLogs": [ { "version": "1.0", @@ -47,4 +50,4 @@ "desc": "测试" } ] -} \ No newline at end of file +} diff --git a/src/main/resources/template/AllInOne.adoc b/src/main/resources/template/AllInOne.adoc index 9948082..7b34312 100644 --- a/src/main/resources/template/AllInOne.adoc +++ b/src/main/resources/template/AllInOne.adoc @@ -64,7 +64,7 @@ for(param in doc.requestParams){ |==================== <%}%> -<%if(isNotEmpty(doc.requestUsage)){%> +<%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%> *Request-example:* ---- ${doc.requestUsage} @@ -85,7 +85,7 @@ for(param in doc.responseParams){ |==================== <%}%> -<%if(isNotEmpty(doc.responseUsage)){%> +<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%> *Response-example:* ---- ${doc.responseUsage} @@ -127,4 +127,4 @@ for(dataDict in dict.dataDictList){ <%}%> |==================== <%}%> -<%}%> \ No newline at end of file +<%}%> diff --git a/src/main/resources/template/AllInOne.btl b/src/main/resources/template/AllInOne.btl index c8e948f..59efa7e 100644 --- a/src/main/resources/template/AllInOne.btl +++ b/src/main/resources/template/AllInOne.btl @@ -1,113 +1,113 @@ -<%if(isNotEmpty(projectName)){%> -# ${projectName} -<%}%> -<%if(isNotEmpty(revisionLogList)){%> -Version | Update Time | Status | Author | Description ----|---|---|---|--- -<% -for(revisionLog in revisionLogList){ -%> -${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks} -<%}%> - -<%}%> - - -<% -for(api in apiDocList){ -%> -## ${api.desc} -<% -for(doc in api.list){ -%> -<%if(doc.deprecated){%> -### ~~${doc.desc}~~ -<%}else{%> -### ${doc.desc} -<%}%> -**URL:** ${doc.url} - -**Type:** ${doc.type} - -<%if(isNotEmpty(doc.author)){%> -**Author:** ${doc.author} -<%}%> - -**Content-Type:** ${doc.contentType} - -**Description:** ${doc.detail} -<%if(isNotEmpty(doc.headers)){%> - -**Request-headers:** - -Header | Type|Description|Required|Since ----|---|---|---|---- -${doc.headers} -<%}%> -<%if(isNotEmpty(doc.requestParams)){%> - -**Request-parameters:** - -Parameter | Type|Description|Required|Since ----|---|---|---|--- -<% -for(param in doc.requestParams){ -%> -${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} -<%}%> -<%}%> - -<%if(isNotEmpty(doc.requestUsage)){%> -**Request-example:** -``` -${doc.requestUsage} -``` -<%}%> -<%if(isNotEmpty(doc.responseParams)){%> -**Response-fields:** - -Field | Type|Description|Since ----|---|---|--- -<% -for(param in doc.responseParams){ -%> -${param.field}|${param.type}|${param.desc}|${param.version} -<%}%> -<%}%> - -<%if(isNotEmpty(doc.responseUsage)){%> -**Response-example:** -``` -${doc.responseUsage} -``` -<%}%> - -<% } %> -<% } %> -<%if(isNotEmpty(errorCodeList)){%> -## ${errorListTitle} -Error code |Description ----|--- -<% -for(error in errorCodeList){ -%> -${error.value}|${error.desc} -<%}%> -<%}%> - -<%if(isNotEmpty(dictList)){%> -## ${dictListTitle} -<% -for(dict in dictList){ -%> -### ${dict.title} - -Code |Type|Description ----|---|--- -<% -for(dataDict in dict.dataDictList){ -%> -${dataDict.value}|${dataDict.type}|${dataDict.desc} -<%}%> -<%}%> -<%}%> \ No newline at end of file +<%if(isNotEmpty(projectName)){%> +# ${projectName} +<%}%> +<%if(isNotEmpty(revisionLogList)){%> +Version | Update Time | Status | Author | Description +---|---|---|---|--- +<% +for(revisionLog in revisionLogList){ +%> +${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revisionLog.author}|${revisionLog.remarks} +<%}%> + +<%}%> + + +<% +for(api in apiDocList){ +%> +## ${api.desc} +<% +for(doc in api.list){ +%> +<%if(doc.deprecated){%> +### ~~${doc.desc}~~ +<%}else{%> +### ${doc.desc} +<%}%> +**URL:** ${doc.url} + +**Type:** ${doc.type} + +<%if(isNotEmpty(doc.author)){%> +**Author:** ${doc.author} +<%}%> + +**Content-Type:** ${doc.contentType} + +**Description:** ${doc.detail} +<%if(isNotEmpty(doc.headers)){%> + +**Request-headers:** + +Header | Type|Description|Required|Since +---|---|---|---|---- +${doc.headers} +<%}%> +<%if(isNotEmpty(doc.requestParams)){%> + +**Request-parameters:** + +Parameter | Type|Description|Required|Since +---|---|---|---|--- +<% +for(param in doc.requestParams){ +%> +${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} +<%}%> +<%}%> + +<%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%> +**Request-example:** +``` +${doc.requestUsage} +``` +<%}%> +<%if(isNotEmpty(doc.responseParams)){%> +**Response-fields:** + +Field | Type|Description|Since +---|---|---|--- +<% +for(param in doc.responseParams){ +%> +${param.field}|${param.type}|${param.desc}|${param.version} +<%}%> +<%}%> + +<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%> +**Response-example:** +``` +${doc.responseUsage} +``` +<%}%> + +<% } %> +<% } %> +<%if(isNotEmpty(errorCodeList)){%> +## ${errorListTitle} +Error code |Description +---|--- +<% +for(error in errorCodeList){ +%> +${error.value}|${error.desc} +<%}%> +<%}%> + +<%if(isNotEmpty(dictList)){%> +## ${dictListTitle} +<% +for(dict in dictList){ +%> +### ${dict.title} + +Code |Type|Description +---|---|--- +<% +for(dataDict in dict.dataDictList){ +%> +${dataDict.value}|${dataDict.type}|${dataDict.desc} +<%}%> +<%}%> +<%}%> diff --git a/src/main/resources/template/AllInOne.html b/src/main/resources/template/AllInOne.html index 9910bf0..496f44b 100644 --- a/src/main/resources/template/AllInOne.html +++ b/src/main/resources/template/AllInOne.html @@ -1,4 +1,4 @@ -<%if(isNotEmpty(projectName)){%>${projectName}<%}else{%>API Reference<%}%>
<%if(isNotEmpty(revisionLogList)){%>
<%for(revisionLog in revisionLogList){%><%}%>
VersionUpdate TimeStatusAuthorDescription

${revisionLog.version}

${revisionLog.revisionTime}

${revisionLog.status}

${revisionLog.author}

${revisionLog.remarks}

<%}%><%for(api in apiDocList){%>

${api.order}. ${api.desc}

<%for(doc in api.list){%>

<%if(doc.deprecated){%>${api.order}.${doc.order}. ${doc.desc}<%}else{%>${api.order}.${doc.order}. ${doc.desc}<%}%>

URL: ${doc.url}

Type: ${doc.type}

<%if(isNotEmpty(doc.author)){%>

Author: ${doc.author}

<%}%>

Content-Type: ${doc.contentType}

Description: ${doc.detail}

<%if(isNotEmpty(doc.requestHeaders)){%>

Request-headers:

<%for(header in doc.requestHeaders){%><%}%>
HeaderTypeDescriptionRequiredSince

${header.name}

${header.type}

${header.desc}

${header.required}

${header.since}

<%}%><%if(isNotEmpty(doc.requestParams)){%>

Request-parameters:

<%for(param in doc.requestParams){%><%}%>
ParameterTypeDescriptionRequiredSince

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

<%}%><%if(isNotEmpty(doc.requestUsage)){%>

Request-example:

${doc.requestUsage}
<%}%><%if(isNotEmpty(doc.responseParams)){%>

Response-fields:

<%for(param in doc.responseParams){%><%}%>
FieldTypeDescriptionSince

${param.field}

${param.type}

${param.desc}

${param.version}

<%}%><%if(isNotEmpty(doc.responseUsage)){%>

Response-example:

${doc.responseUsage}
<%}%>
<%}%>
<%}%><%if(isNotEmpty(errorCodeList)){%>

${apiDocList.~size+1}. ${errorListTitle}

<%for(error in errorCodeList){%><%}%>
Error codeDescription

${error.value}

${error.desc}

<%}%><%if(isNotEmpty(dictList)){%>

${dictListOrder}. ${dictListTitle}

<% for(dict in dictList){ %>

${dictListOrder}.${dict.order}. ${dict.title}

<%for(dataDict in dict.dataDictList){%><%}%>
CodeTypeDescription

${dataDict.value}

${dataDict.type}

${dataDict.desc}

<%}%>
<%}%>
Generated by smart-doc at ${createTime}Suggestions,contact,support and error reporting on Gitee or Github
+<%if(isNotEmpty(projectName)){%>${projectName}<%}else{%>API Reference<%}%>
<%if(isNotEmpty(revisionLogList)){%>
<%for(revisionLog in revisionLogList){%><%}%>
VersionUpdate TimeStatusAuthorDescription

${revisionLog.version}

${revisionLog.revisionTime}

${revisionLog.status}

${revisionLog.author}

${revisionLog.remarks}

<%}%><%for(api in apiDocList){%>

${api.order}. ${api.desc}

<%for(doc in api.list){%>

<%if(doc.deprecated){%>${api.order}.${doc.order}. ${doc.desc}<%}else{%>${api.order}.${doc.order}. ${doc.desc}<%}%>

URL: ${doc.url}

Type: ${doc.type}

<%if(isNotEmpty(doc.author)){%>

Author: ${doc.author}

<%}%>

Content-Type: ${doc.contentType}

Description: ${doc.detail}

<%if(isNotEmpty(doc.requestHeaders)){%>

Request-headers:

<%for(header in doc.requestHeaders){%><%}%>
HeaderTypeDescriptionRequiredSince

${header.name}

${header.type}

${header.desc}

${header.required}

${header.since}

<%}%><%if(isNotEmpty(doc.requestParams)){%>

Request-parameters:

<%for(param in doc.requestParams){%><%}%>
ParameterTypeDescriptionRequiredSince

${param.field}

${param.type}

${param.desc}

${param.required}

${param.version}

<%}%><%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%>

Request-example:

${doc.requestUsage}
<%}%><%if(isNotEmpty(doc.responseParams)){%>

Response-fields:

<%for(param in doc.responseParams){%><%}%>
FieldTypeDescriptionSince

${param.field}

${param.type}

${param.desc}

${param.version}

<%}%><%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%>

Response-example:

${doc.responseUsage}
<%}%>
<%}%>
<%}%><%if(isNotEmpty(errorCodeList)){%>

${apiDocList.~size+1}. ${errorListTitle}

<%for(error in errorCodeList){%><%}%>
Error codeDescription

${error.value}

${error.desc}

<%}%><%if(isNotEmpty(dictList)){%>

${dictListOrder}. ${dictListTitle}

<% for(dict in dictList){ %>

${dictListOrder}.${dict.order}. ${dict.title}

<%for(dataDict in dict.dataDictList){%><%}%>
CodeTypeDescription

${dataDict.value}

${dataDict.type}

${dataDict.desc}

<%}%>
<%}%>
Generated by smart-doc at ${createTime}Suggestions,contact,support and error reporting on Gitee or Github
- \ No newline at end of file + diff --git a/src/main/resources/template/ApiDoc.adoc b/src/main/resources/template/ApiDoc.adoc index d65efd2..d9b9d1c 100644 --- a/src/main/resources/template/ApiDoc.adoc +++ b/src/main/resources/template/ApiDoc.adoc @@ -46,7 +46,7 @@ for(param in doc.requestParams){ <%}%> |==================== -<%if(isNotEmpty(doc.requestUsage)){%> +<%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%> *Request-example:* ---- ${doc.requestUsage} @@ -67,7 +67,7 @@ for(param in doc.responseParams){ <%}%> |==================== -<%if(isNotEmpty(doc.responseUsage)){%> +<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%> *Response-example:* ---- ${doc.responseUsage} diff --git a/src/main/resources/template/ApiDoc.btl b/src/main/resources/template/ApiDoc.btl index c70518d..2b76d44 100644 --- a/src/main/resources/template/ApiDoc.btl +++ b/src/main/resources/template/ApiDoc.btl @@ -40,7 +40,7 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version} <%}%> <%}%> -<%if(isNotEmpty(doc.requestUsage)){%> +<%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%> **Request-example:** ``` ${doc.requestUsage} @@ -58,7 +58,7 @@ ${param.field}|${param.type}|${param.desc}|${param.version} <%}%> <%}%> -<%if(isNotEmpty(doc.responseUsage)){%> +<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%> **Response-example:** ``` ${doc.responseUsage} diff --git a/src/main/resources/template/index-temp.btl b/src/main/resources/template/index-temp.btl index 704ec20..009bc97 100644 --- a/src/main/resources/template/index-temp.btl +++ b/src/main/resources/template/index-temp.btl @@ -91,7 +91,7 @@ <%}%> - <%if(isNotEmpty(doc.requestUsage)){%> + <%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%>

Request-example:

${doc.requestUsage}
@@ -113,7 +113,7 @@ <%}%> - <%if(isNotEmpty(doc.responseUsage)){%> + <%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%>

Response-example:

${doc.responseUsage}
@@ -132,4 +132,4 @@ - \ No newline at end of file +