support for deprecated annotation and javadoc tag

Author: jmisur

docs/index.html

@@ -1637,7 +1637,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-10-30 09:01:48 CET
+Last updated 2017-10-30 21:25:03 CET
 </div>
 </div>
 <link rel="stylesheet" href="highlight/styles/github.min.css">

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/OperationAttributeHelper.java

@@ -30,6 +30,7 @@
 import capital.scalable.restdocs.constraints.ConstraintReader;
 import capital.scalable.restdocs.javadoc.JavadocReader;
 import capital.scalable.restdocs.misc.AuthorizationSnippet;
+import capital.scalable.restdocs.util.TemplateFormatting;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.restdocs.RestDocumentationContext;
@@ -46,9 +47,6 @@ public class OperationAttributeHelper {
             "org.springframework.restdocs.configuration";
     public static final String REQUEST_PATTERN = "REQUEST_PATTERN";
 
-    private static final String LINE_BREAK_ASCIIDOC = " +\n";
-    private static final String LINE_BREAK_MARKDOWN = "<br>";
-
     public static HandlerMethod getHandlerMethod(Operation operation) {
         Map<String, Object> attributes = operation.getAttributes();
         return (HandlerMethod) attributes.get(HandlerMethod.class.getName());
@@ -131,13 +129,12 @@ public static List<Snippet> getDefaultSnippets(Operation operation) {
         return (List<Snippet>) operation.getAttributes().get(ATTRIBUTE_NAME_DEFAULT_SNIPPETS);
     }
 
-    public static String determineForcedLineBreak(Operation operation) {
-        return determineForcedLineBreak(getTemplateFormat(operation));
+    public static TemplateFormatting determineTemplateFormatting(Operation operation) {
+        return determineTemplateFormatting(getTemplateFormat(operation));
     }
 
-    // necessary until https://github.com/spring-projects/spring-restdocs/issues/351 is fixed
-    public static String determineForcedLineBreak(TemplateFormat templateFormat) {
+    public static TemplateFormatting determineTemplateFormatting(TemplateFormat templateFormat) {
         return templateFormat.getId().equals(TemplateFormats.asciidoctor().getId())
-                ? LINE_BREAK_ASCIIDOC : LINE_BREAK_MARKDOWN;
+                ? TemplateFormatting.ASCIIDOC : TemplateFormatting.MARKDOWN;
     }
 }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/constraints/ConstraintReader.java

@@ -23,6 +23,7 @@
 public interface ConstraintReader {
     String CONSTRAINTS_ATTRIBUTE = "constraints";
     String OPTIONAL_ATTRIBUTE = "optionals";
+    String DEPRECATED_ATTRIBUTE = "deprecated";
 
     List<String> getConstraintMessages(Class<?> javaBaseClass, String javaFieldName);
 

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/constraints/ConstraintReaderImpl.java

@@ -19,7 +19,7 @@
 import static capital.scalable.restdocs.constraints.ConstraintAndGroupDescriptionResolver.VALUE;
 import static capital.scalable.restdocs.constraints.MethodParameterValidatorConstraintResolver
         .CONSTRAINT_CLASS;
-import static capital.scalable.restdocs.util.ObjectUtil.arrayToString;
+import static capital.scalable.restdocs.util.FormatUtil.arrayToString;
 import static java.util.Collections.emptyList;
 import static java.util.Collections.singletonList;
 import static java.util.Collections.singletonMap;

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/constraints/HumanReadableConstraintResolver.java

@@ -16,7 +16,7 @@
 
 package capital.scalable.restdocs.constraints;
 
-import static capital.scalable.restdocs.util.ObjectUtil.arrayToString;
+import static capital.scalable.restdocs.util.FormatUtil.arrayToString;
 import static org.slf4j.LoggerFactory.getLogger;
 
 import java.util.ArrayList;

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/jackson/FieldDocumentationVisitorContext.java

@@ -17,14 +17,17 @@
 package capital.scalable.restdocs.jackson;
 
 import static capital.scalable.restdocs.constraints.ConstraintReader.CONSTRAINTS_ATTRIBUTE;
+import static capital.scalable.restdocs.constraints.ConstraintReader.DEPRECATED_ATTRIBUTE;
 import static capital.scalable.restdocs.constraints.ConstraintReader.OPTIONAL_ATTRIBUTE;
 import static capital.scalable.restdocs.util.FieldUtil.fromGetter;
 import static capital.scalable.restdocs.util.FieldUtil.isGetter;
 import static capital.scalable.restdocs.util.TypeUtil.isPrimitive;
 import static org.apache.commons.lang3.StringUtils.isBlank;
+import static org.apache.commons.lang3.StringUtils.isNotBlank;
 import static org.slf4j.LoggerFactory.getLogger;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 
+import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -35,6 +38,7 @@
 import org.slf4j.Logger;
 import org.springframework.restdocs.payload.FieldDescriptor;
 import org.springframework.restdocs.snippet.Attributes.Attribute;
+import org.springframework.util.ReflectionUtils;
 
 class FieldDocumentationVisitorContext {
     private static final Logger log = getLogger(FieldDocumentationVisitorContext.class);
@@ -74,7 +78,8 @@ public void addField(InternalFieldInfo info, String jsonType) {
 
         Attribute constraints = constraintAttribute(javaBaseClass, javaFieldName);
         Attribute optionals = optionalAttribute(javaBaseClass, javaFieldName);
-        fieldDescriptor.attributes(constraints, optionals);
+        Attribute deprecated = deprecatedAttribute(javaBaseClass, javaFieldName);
+        fieldDescriptor.attributes(constraints, optionals, deprecated);
 
         fields.add(fieldDescriptor);
         log.debug("({}) {} added", jsonFieldPath, javaFieldTypeName);
@@ -116,6 +121,11 @@ private Attribute optionalAttribute(Class<?> javaBaseClass, String javaFieldName
                 resolveOptionalMessages(javaBaseClass, javaFieldName));
     }
 
+    private Attribute deprecatedAttribute(Class<?> javaBaseClass, String javaFieldName) {
+        return new Attribute(DEPRECATED_ATTRIBUTE,
+                resolveDeprecatedMessage(javaBaseClass, javaFieldName));
+    }
+
     private List<String> resolveOptionalMessages(Class<?> javaBaseClass, String javaFieldName) {
         List<String> optionalMessages = new ArrayList<>();
 
@@ -156,4 +166,13 @@ private List<String> resolveConstraintDescriptions(Class<?> javaBaseClass,
 
         return descriptions;
     }
+
+    private String resolveDeprecatedMessage(Class<?> javaBaseClass, String javaFieldName) {
+        Field field = ReflectionUtils.findField(javaBaseClass, javaFieldName);
+        boolean isDeprecated = field == null
+                ? false
+                : field.getAnnotation(Deprecated.class) != null;
+        String comment = javadocReader.resolveFieldTag(javaBaseClass, javaFieldName, "deprecated");
+        return isDeprecated || isNotBlank(comment) ? comment : null;
+    }
 }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/ClassJavadoc.java

@@ -16,7 +16,7 @@
 
 package capital.scalable.restdocs.javadoc;
 
-import static org.springframework.util.StringUtils.hasText;
+import static org.apache.commons.lang3.StringUtils.trimToEmpty;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -75,10 +75,6 @@ public String getFieldTag(String javaFieldName, String tagName) {
         }
     }
 
-    private static String trimToEmpty(String value) {
-        return hasText(value) ? value : "";
-    }
-
     static class MethodJavadoc {
         private String comment;
         private Map<String, String> parameters = new HashMap<>();

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/JavadocUtil.java

@@ -1,5 +1,7 @@
 package capital.scalable.restdocs.javadoc;
 
+import capital.scalable.restdocs.util.TemplateFormatting;
+
 public class JavadocUtil {
     private static String FORCED_LB = "__FLB__";
     private static String LB = "__LB__";
@@ -8,7 +10,7 @@ private JavadocUtil() {
         // util
     }
 
-    public static String convertFromJavadoc(String javadoc, String forcedLineBreak) {
+    public static String convertFromJavadoc(String javadoc, TemplateFormatting templateFormatting) {
         String converted = javadoc.toString()
                 // line breaks in javadoc are ignored
                 .replace("\n", "")
@@ -21,13 +23,17 @@ public static String convertFromJavadoc(String javadoc, String forcedLineBreak)
                 .replace("<ul>", LB)
                 .replace("</ul>", LB + LB)
                 .replace("<li>", LB + "- ")
-                .replace("</li>", "");
+                .replace("</li>", "")
+                .replace("<b>", templateFormatting.getBold())
+                .replace("</b>", templateFormatting.getBold())
+                .replace("<i>", templateFormatting.getItalics())
+                .replace("</i>", templateFormatting.getItalics());
 
         if (converted.isEmpty()) {
             return "";
         }
 
-        String res = trimAndFixLineBreak(converted, FORCED_LB, forcedLineBreak);
+        String res = trimAndFixLineBreak(converted, FORCED_LB, templateFormatting.getLineBreak());
         res = trimAndFixLineBreak(res, LB, "\n");
         return res.toString();
     }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/DescriptionSnippet.java

@@ -16,10 +16,13 @@
 
 package capital.scalable.restdocs.misc;
 
-import static capital.scalable.restdocs.OperationAttributeHelper.determineForcedLineBreak;
+import static capital.scalable.restdocs.OperationAttributeHelper.determineTemplateFormatting;
 import static capital.scalable.restdocs.OperationAttributeHelper.getHandlerMethod;
 import static capital.scalable.restdocs.OperationAttributeHelper.getJavadocReader;
 import static capital.scalable.restdocs.javadoc.JavadocUtil.convertFromJavadoc;
+import static capital.scalable.restdocs.util.FormatUtil.addDot;
+import static org.apache.commons.lang3.StringUtils.capitalize;
+import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -46,14 +49,31 @@ protected Map<String, Object> createModel(Operation operation) {
         }
 
         JavadocReader javadocReader = getJavadocReader(operation);
+        String methodComment = resolveComment(handlerMethod, javadocReader);
+        String deprecated = resolveDeprecated(handlerMethod, javadocReader);
+        String description = convertFromJavadoc(deprecated + methodComment,
+                determineTemplateFormatting(operation));
 
-        String methodComment = javadocReader.resolveMethodComment(handlerMethod.getBeanType(),
-                handlerMethod.getMethod().getName());
+        model.put("description", description);
+        return model;
+    }
 
-        methodComment = convertFromJavadoc(methodComment, determineForcedLineBreak(operation));
+    private String resolveDeprecated(HandlerMethod handlerMethod, JavadocReader javadocReader) {
+        boolean isDeprecated = handlerMethod.getMethod().getAnnotation(Deprecated.class) != null;
+        String comment = javadocReader.resolveMethodTag(handlerMethod.getBeanType(),
+                handlerMethod.getMethod().getName(), "deprecated");
+        if (isDeprecated || isNotBlank(comment)) {
+            comment = capitalize(addDot(comment));
+            return "<b>Deprecated.</b> " + comment + "<p>";
+        } else {
+            return "";
+        }
+    }
 
-        model.put("description", methodComment);
-        return model;
+    private String resolveComment(HandlerMethod handlerMethod, JavadocReader javadocReader) {
+        String methodComment = javadocReader.resolveMethodComment(handlerMethod.getBeanType(),
+                handlerMethod.getMethod().getName());
+        return capitalize(addDot(methodComment));
     }
 
     private Map<String, Object> defaultModel() {

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/AbstractParameterSnippet.java

@@ -20,6 +20,7 @@
 import static capital.scalable.restdocs.OperationAttributeHelper.getHandlerMethod;
 import static capital.scalable.restdocs.OperationAttributeHelper.getJavadocReader;
 import static capital.scalable.restdocs.constraints.ConstraintReader.CONSTRAINTS_ATTRIBUTE;
+import static capital.scalable.restdocs.constraints.ConstraintReader.DEPRECATED_ATTRIBUTE;
 import static capital.scalable.restdocs.constraints.ConstraintReader.OPTIONAL_ATTRIBUTE;
 import static capital.scalable.restdocs.util.FieldDescriptorUtil.assertAllDocumented;
 import static capital.scalable.restdocs.util.TypeUtil.determineTypeName;
@@ -88,7 +89,8 @@ private void addFieldDescriptor(HandlerMethod handlerMethod,
 
         Attribute constraints = constraintAttribute(param, constraintReader);
         Attribute optionals = optionalsAttribute(param, annot);
-        descriptor.attributes(constraints, optionals);
+        Attribute deprecated = deprecatedAttribute(param, annot, javadocReader);
+        descriptor.attributes(constraints, optionals, deprecated);
 
         fieldDescriptors.add(descriptor);
     }
@@ -102,6 +104,12 @@ protected Attribute optionalsAttribute(MethodParameter param, A annot) {
         return new Attribute(OPTIONAL_ATTRIBUTE, singletonList(!isRequired(param, annot)));
     }
 
+    protected Attribute deprecatedAttribute(MethodParameter param, A annot,
+            JavadocReader javadocReader) {
+        return new Attribute(DEPRECATED_ATTRIBUTE,
+                param.getParameterAnnotation(Deprecated.class) != null ? "" : null);
+    }
+
     protected abstract boolean isRequired(MethodParameter param, A annot);
 
     protected abstract String getPath(A annot);