Merge branch 'dev' of https://github.com/smart-doc-group/smart-doc

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
 - 更新内容：

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.
 ```
 <plugin>
     <groupId>com.github.shalousun</groupId>
@@ -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)
 

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
 ```
 <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)

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <artifactId>smart-doc</artifactId>
     <packaging>jar</packaging>
-    <version>1.8.9</version>
+    <version>1.9.0</version>
 
     <name>smart-doc</name>
     <url>https://github.com/shalousun/smart-doc.git</url>
@@ -32,7 +32,7 @@
     </developers>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <flexmark.version>0.61.32</flexmark.version>
+        <flexmark.version>0.62.2</flexmark.version>
     </properties>
     <dependencies>
         <dependency>
@@ -44,7 +44,7 @@
         <dependency>
             <groupId>com.ibeetl</groupId>
             <artifactId>beetl</artifactId>
-            <version>3.1.6.RELEASE</version>
+            <version>3.1.8.RELEASE</version>
         </dependency>
         <dependency>
             <groupId>com.thoughtworks.qdox</groupId>
@@ -55,6 +55,12 @@
             <groupId>com.github.javafaker</groupId>
             <artifactId>javafaker</artifactId>
             <version>1.0.2</version>
+            <exclusions>
+                <exclusion>
+                    <artifactId>commons-lang3</artifactId>
+                    <groupId>org.apache.commons</groupId>
+                </exclusion>
+            </exclusions>
         </dependency>
         <dependency>
             <groupId>com.github.shalousun</groupId>

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 {

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<ApiDocDict> apiDocDictList = builderTemplate.buildDictionary(config, javaProjectBuilder);

src/main/java/com/power/doc/constants/DocAnnotationConstants.java

@@ -34,4 +34,6 @@ public interface DocAnnotationConstants {
     String DEFAULT_VALUE_PROP = "defaultValue";
 
     String REQUEST_MAPPING = "RequestMapping";
+
+    String DEPRECATED = "Deprecated";
 }

src/main/java/com/power/doc/constants/DubboAnnotationConstants.java

@@ -5,5 +5,11 @@ package com.power.doc.constants;
  * @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";
 }

src/main/java/com/power/doc/constants/TemplateVariable.java

@@ -46,9 +46,9 @@ public enum TemplateVariable {
     PROTOCOL("protocol"),
     AUTHOR("author"),
     URI("uri"),
-    RPC_CONSUMER_CONFIG("consumerConfigExample")
+    RPC_CONSUMER_CONFIG("consumerConfigExample"),
-    ;
+    REQUEST_EXAMPLE("isRequestExample"),
-
+    RESPONSE_EXAMPLE("isResponseExample");
 
     private String variable;
 

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)) {

src/main/java/com/power/doc/helper/JsonBuildHelper.java

@@ -75,10 +75,7 @@ public class JsonBuildHelper {
                                    boolean isResp, int counter, Map<String, String> registryClasses, ProjectDocConfigBuilder builder) {
 
         //存储泛型所对应的实体类
-        Map<String,String> genericMap = new HashMap<>(10);
+        Map<String, String> 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<JavaTypeVariable<JavaGenericDeclaration>> variables = cls.getTypeParameters();
-            for(int i=0;i<cls.getTypeParameters().size();i++){
+            for (int i = 0; i < cls.getTypeParameters().size(); i++) {
-                genericMap.put(variables.get(i).getName(),globGicName[i]);
+                genericMap.put(variables.get(i).getName(), globGicName[i]);
             }
         }
         StringBuilder data = new StringBuilder();
@@ -200,9 +196,9 @@ public class JsonBuildHelper {
                 List<JavaAnnotation> 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) {
+                        } else if (globGicName.length > 0) {
-                            String gicName = genericMap.get(subTypeName)==null ? globGicName[0] : genericMap.get(subTypeName);
+                            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("\",");

src/main/java/com/power/doc/model/ApiConfig.java

@@ -188,22 +188,45 @@ public class ApiConfig {
 
     /**
      * 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;
@@ -447,5 +470,27 @@ public class ApiConfig {
         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;
+    }
 }

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<RpcApiDoc> {
             List<JavaAnnotation> 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<RpcApiDoc> {
         List<JavaAnnotation> 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<RpcApiDoc> {
         return false;
     }
 
-    private void handleJavaApiDoc(JavaClass cls, List<RpcApiDoc> apiDocList, List<JavaMethodDoc> apiMethodDocs, int order, ProjectDocConfigBuilder builder) {
+    private void handleJavaApiDoc(JavaClass cls, List<RpcApiDoc> apiDocList, List<JavaMethodDoc> apiMethodDocs,
+                                  int order, ProjectDocConfigBuilder builder) {
         String className = cls.getCanonicalName();
         List<JavaType> javaTypes = cls.getImplements();
         if (javaTypes.size() >= 1 && !cls.isInterface()) {

src/main/java/com/power/doc/utils/JavaClassUtil.java

@@ -266,6 +266,11 @@ public class JavaClassUtil {
         List<String> validates = DocValidatorAnnotationEnum.listValidatorAnnotations();
         List<AnnotationValue> 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

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",

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}

src/main/resources/template/AllInOne.btl

@@ -57,7 +57,7 @@ ${param.field}|${param.type}|${param.desc}|${param.required}|${param.version}
 <%}%>
 <%}%>
 
-<%if(isNotEmpty(doc.requestUsage)){%>
+<%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%>
 **Request-example:**
 ```
 ${doc.requestUsage}
@@ -75,7 +75,7 @@ ${param.field}|${param.type}|${param.desc}|${param.version}
 <%}%>
 <%}%>
 
-<%if(isNotEmpty(doc.responseUsage)){%>
+<%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%>
 **Response-example:**
 ```
 ${doc.responseUsage}

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}

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}

src/main/resources/template/index-temp.btl

@@ -91,7 +91,7 @@
              </tbody>
              </table>
              <%}%>
-             <%if(isNotEmpty(doc.requestUsage)){%>
+             <%if(isNotEmpty(doc.requestUsage)&&isRequestExample){%>
              <p><strong>Request-example:</strong></p>
              <pre><code>${doc.requestUsage}
              </code></pre>
@@ -113,7 +113,7 @@
              </table>
              <%}%>
 
-             <%if(isNotEmpty(doc.responseUsage)){%>
+             <%if(isNotEmpty(doc.responseUsage)&&isResponseExample){%>
               <p><strong>Response-example:</strong></p>
               <pre><code>${doc.responseUsage}
               </code></pre>