Custom subtypes (#317)

Ability to set specifier for fields in subtypes. It's then shown after optional, description or constraints message. Works for Jackson mapped subtypes or manually mapped.

Author: jmisur

samples/java-webmvc/src/test/java/capital/scalable/restdocs/example/testsupport/MockMvcBase.java

@@ -7,9 +7,9 @@
  * Licensed 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.
@@ -51,6 +51,9 @@
 
 import javax.servlet.Filter;
 
+import capital.scalable.restdocs.example.items.Metadata;
+import capital.scalable.restdocs.example.items.Metadata3;
+import capital.scalable.restdocs.jackson.TypeMapping;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.Before;
 import org.junit.Rule;
@@ -97,7 +100,8 @@ public void setUp() throws Exception {
         this.mockMvc = MockMvcBuilders
                 .webAppContextSetup(context)
                 .addFilters(springSecurityFilterChain)
-                .alwaysDo(prepareJackson(objectMapper))
+                .alwaysDo(prepareJackson(objectMapper, new TypeMapping()
+                        .mapSubtypes(Metadata.class, Metadata3.class))) // custom
                 .alwaysDo(commonDocumentation())
                 .apply(documentationConfiguration(restDocumentation)
                         .uris()

samples/shared/src/main/java/capital/scalable/restdocs/example/items/Metadata1.java

@@ -22,7 +22,7 @@
 
 public class Metadata1 extends Metadata {
     /**
-     * Tag attribute. Available only if metadata type=1
+     * Tag attribute.
      */
     private String tag;
 

samples/shared/src/main/java/capital/scalable/restdocs/example/items/Metadata2.java

@@ -24,7 +24,7 @@
 
 public class Metadata2 extends Metadata {
     /**
-     * Order attribute. Available only if metadata type=2
+     * Order attribute.
      */
     private Integer order;
 

samples/shared/src/main/java/capital/scalable/restdocs/example/items/Metadata3.java

@@ -0,0 +1,33 @@
+/*-
+ * #%L
+ * Spring Auto REST Docs Shared POJOs Example Project
+ * %%
+ * Copyright (C) 2015 - 2019 Scalable Capital GmbH
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+
+package capital.scalable.restdocs.example.items;
+
+public class Metadata3 extends Metadata {
+    /**
+     * Tag attribute.
+     */
+    private String tag;
+
+    /**
+     * Info attribute.
+     */
+    private String info;
+}

samples/shared/src/main/resources/org/springframework/restdocs/constraints/ConstraintDescriptions.properties

@@ -1,4 +1,7 @@
 capital.scalable.restdocs.example.constraints.OneOf.description=Must be one of ${value}
 capital.scalable.restdocs.example.constraints.English.description=EN: ${value}
 capital.scalable.restdocs.example.constraints.German.description=DE: ${value}
-capital.scalable.restdocs.example.constraints.Id.description=Must be a valid ID
+capital.scalable.restdocs.example.constraints.Id.description=Must be a valid ID
+capital.scalable.restdocs.example.items.Metadata1.description=Available if metadata type=1
+capital.scalable.restdocs.example.items.Metadata2.description=Available if metadata type=2
+capital.scalable.restdocs.example.items.Metadata3.description=Available in specific conditions

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

@@ -30,6 +30,7 @@
 import java.util.Map;
 
 import capital.scalable.restdocs.constraints.ConstraintReader;
+import capital.scalable.restdocs.jackson.TypeMapping;
 import capital.scalable.restdocs.javadoc.JavadocReader;
 import capital.scalable.restdocs.misc.AuthorizationSnippet;
 import capital.scalable.restdocs.util.TemplateFormatting;
@@ -119,6 +120,16 @@ public static void setConstraintReader(MockHttpServletRequest request,
                 .put(ConstraintReader.class.getName(), constraintReader);
     }
 
+    public static TypeMapping getTypeMapping(Operation operation) {
+        TypeMapping typeMapping = (TypeMapping) operation.getAttributes().get(TypeMapping.class.getName());
+        return typeMapping != null ? typeMapping : new TypeMapping();
+    }
+
+    public static void setTypeMapping(MockHttpServletRequest request, TypeMapping typeMapping) {
+        ((Map) request.getAttribute(ATTRIBUTE_NAME_CONFIGURATION))
+                .put(TypeMapping.class.getName(), typeMapping);
+    }
+
     public static TemplateFormat getTemplateFormat(Operation operation) {
         StandardWriterResolver writerResolver = (StandardWriterResolver) operation.getAttributes()
                 .get(WriterResolver.class.getName());

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

@@ -25,10 +25,13 @@
 
 public interface ConstraintReader {
     String CONSTRAINTS_ATTRIBUTE = "constraints";
+    String TYPE_ATTRIBUTE = "type";
     String OPTIONAL_ATTRIBUTE = "optionals";
     String DEPRECATED_ATTRIBUTE = "deprecated";
     String DEFAULT_VALUE_ATTRIBUTE = "default-value";
 
+    String getTypeSpecifier(Class<?> javaBaseClass);
+
     List<String> getConstraintMessages(Class<?> javaBaseClass, String javaFieldName);
 
     List<String> getConstraintMessages(MethodParameter param);

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

@@ -24,6 +24,7 @@
 import static capital.scalable.restdocs.i18n.SnippetTranslationResolver.translate;
 import static capital.scalable.restdocs.util.FormatUtil.collectionToString;
 import static java.util.Collections.emptyList;
+import static java.util.Collections.emptyMap;
 import static java.util.Collections.singletonList;
 import static java.util.Collections.singletonMap;
 import static org.apache.commons.lang3.StringUtils.isBlank;
@@ -82,6 +83,19 @@ public List<String> getOptionalMessages(Class<?> javaBaseClass, String javaField
         return skippableConstraintResolver.getOptionalMessages(javaFieldName, javaBaseClass);
     }
 
+    @Override
+    public String getTypeSpecifier(Class<?> javaBaseClass) {
+        String message = constraintDescriptionResolver.resolveDescription(
+                new Constraint(javaBaseClass.getCanonicalName(), emptyMap()));
+
+        // fallback
+        if (message.equals(javaBaseClass.getCanonicalName())) {
+            return "";
+        }
+
+        return message;
+    }
+
     @Override
     public List<String> getConstraintMessages(Class<?> javaBaseClass, String javaFieldName) {
         ConstraintDescriptions constraints = new ConstraintDescriptions(javaBaseClass,

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

@@ -0,0 +1,40 @@
+/*-
+ * #%L
+ * Spring Auto REST Docs Core
+ * %%
+ * Copyright (C) 2015 - 2019 Scalable Capital GmbH
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+package capital.scalable.restdocs.jackson;
+
+import java.util.List;
+
+public class DeprecatedAttribute {
+    private boolean isDeprecated;
+    private List<String> values;
+
+    public DeprecatedAttribute(boolean isDeprecated, List<String> values) {
+        this.isDeprecated = isDeprecated;
+        this.values = values;
+    }
+
+    public boolean isDeprecated() {
+        return isDeprecated;
+    }
+
+    public List<String> getValues() {
+        return values;
+    }
+}

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

@@ -43,26 +43,29 @@ public class FieldDocumentationGenerator {
     private final DeserializationConfig deserializationConfig;
     private final JavadocReader javadocReader;
     private final ConstraintReader constraintReader;
+    private final TypeMapping typeMapping;
 
     public FieldDocumentationGenerator(ObjectWriter writer,
             DeserializationConfig deserializationConfig,
             JavadocReader javadocReader,
-            ConstraintReader constraintReader) {
+            ConstraintReader constraintReader,
+            TypeMapping typeMapping) {
         this.writer = writer;
         this.deserializationConfig = deserializationConfig;
         this.javadocReader = javadocReader;
         this.constraintReader = constraintReader;
+        this.typeMapping = typeMapping;
     }
 
     public FieldDescriptors generateDocumentation(Type baseType, TypeFactory typeFactory)
             throws JsonMappingException {
         JavaType javaBaseType = typeFactory.constructType(baseType);
-        List<JavaType> types = resolveAllTypes(javaBaseType, typeFactory);
+        List<JavaType> types = resolveAllTypes(javaBaseType, typeFactory, typeMapping);
         FieldDescriptors result = new FieldDescriptors();
 
         FieldDocumentationVisitorWrapper visitorWrapper = FieldDocumentationVisitorWrapper.create(
                 javadocReader, constraintReader, deserializationConfig,
-                new TypeRegistry(types), typeFactory);
+                new TypeRegistry(typeMapping, types), typeFactory);
 
         for (JavaType type : types) {
             log.debug("(TOP) {}", type.getRawClass().getSimpleName());