From 94d5e2d94f2dc6a509f3da5e5dd71e1870b53ae1 Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Tue, 8 Sep 2015 14:49:51 +0100 Subject: [PATCH] Improve the extensibility of the descriptor classes This commit improves the extensibility of the various descriptor classes. The following changes have been made: - Constructors have been made protected to allow them to be called by subclasses in a different package - Model creation has been moved to the relevant snippet class. This improves the separation of concerns as a descriptor should not be aware of template-based rendering and the need for a model. The method is protected to allow it to be overridden by a custom subclass that uses a custom descriptor subclass. - Methods that should not be overridden have been made final. See gh-73 --- .../restdocs/hypermedia/LinkDescriptor.java | 43 +++++++++------ .../restdocs/hypermedia/LinksSnippet.java | 17 +++++- .../payload/AbstractFieldsSnippet.java | 18 ++++++- .../restdocs/payload/FieldDescriptor.java | 53 ++++++++++++------- .../request/AbstractParametersSnippet.java | 16 +++++- .../restdocs/request/ParameterDescriptor.java | 35 ++++++------ .../restdocs/snippet/AbstractDescriptor.java | 4 +- 7 files changed, 129 insertions(+), 57 deletions(-) diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinkDescriptor.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinkDescriptor.java index 06689592..9d11f915 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinkDescriptor.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinkDescriptor.java @@ -16,9 +16,6 @@ package org.springframework.restdocs.hypermedia; -import java.util.HashMap; -import java.util.Map; - import org.springframework.restdocs.snippet.AbstractDescriptor; /** @@ -36,7 +33,12 @@ public class LinkDescriptor extends AbstractDescriptor { private boolean optional; - LinkDescriptor(String rel) { + /** + * Creates a new {@code LinkDescriptor} describing a link with the given {@code rel}. + * + * @param rel the rel of the link + */ + protected LinkDescriptor(String rel) { this.rel = rel; } @@ -46,7 +48,7 @@ public class LinkDescriptor extends AbstractDescriptor { * @param description The link's description * @return {@code this} */ - public LinkDescriptor description(String description) { + public final LinkDescriptor description(String description) { this.description = description; return this; } @@ -56,29 +58,36 @@ public class LinkDescriptor extends AbstractDescriptor { * * @return {@code this} */ - public LinkDescriptor optional() { + public final LinkDescriptor optional() { this.optional = true; return this; } - String getRel() { + /** + * Returns the rel of the link described by this descriptor + * + * @return the rel + */ + public final String getRel() { return this.rel; } - String getDescription() { + /** + * Returns the description for the link + * + * @return the link description + */ + public final String getDescription() { return this.description; } - boolean isOptional() { + /** + * Returns {@code true} if the described link is optional, otherwise {@code false} + * + * @return {@code true} if the described link is optional, otherwise {@code false} + */ + public final boolean isOptional() { return this.optional; } - Map toModel() { - Map model = new HashMap<>(); - model.put("rel", this.rel); - model.put("description", this.description); - model.put("optional", this.optional); - model.putAll(getAttributes()); - return model; - } } diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinksSnippet.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinksSnippet.java index edacab16..006327bb 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinksSnippet.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinksSnippet.java @@ -131,7 +131,7 @@ public class LinksSnippet extends TemplatedSnippet { private List> createLinksModel() { List> model = new ArrayList<>(); for (Entry entry : this.descriptorsByRel.entrySet()) { - model.add(entry.getValue().toModel()); + model.add(createModelForDescriptor(entry.getValue())); } return model; } @@ -146,4 +146,19 @@ public class LinksSnippet extends TemplatedSnippet { return this.descriptorsByRel; } + /** + * Returns a model for the given {@code descriptor} + * + * @param descriptor the descriptor + * @return the model + */ + protected Map createModelForDescriptor(LinkDescriptor descriptor) { + Map model = new HashMap<>(); + model.put("rel", descriptor.getRel()); + model.put("description", descriptor.getDescription()); + model.put("optional", descriptor.isOptional()); + model.putAll(descriptor.getAttributes()); + return model; + } + } \ No newline at end of file diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractFieldsSnippet.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractFieldsSnippet.java index 80cd3708..970cd7ec 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractFieldsSnippet.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractFieldsSnippet.java @@ -77,7 +77,7 @@ public abstract class AbstractFieldsSnippet extends TemplatedSnippet { List> fields = new ArrayList<>(); model.put("fields", fields); for (FieldDescriptor descriptor : this.fieldDescriptors) { - fields.add(descriptor.toModel()); + fields.add(createModelForDescriptor(descriptor)); } return model; } @@ -156,4 +156,20 @@ public abstract class AbstractFieldsSnippet extends TemplatedSnippet { return this.fieldDescriptors; } + /** + * Returns a model for the given {@code descriptor} + * + * @param descriptor the descriptor + * @return the model + */ + protected Map createModelForDescriptor(FieldDescriptor descriptor) { + Map model = new HashMap(); + model.put("path", descriptor.getPath()); + model.put("type", descriptor.getType().toString()); + model.put("description", descriptor.getDescription()); + model.put("optional", descriptor.isOptional()); + model.putAll(descriptor.getAttributes()); + return model; + } + } \ No newline at end of file diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldDescriptor.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldDescriptor.java index 5cbf6384..b9cac2df 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldDescriptor.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldDescriptor.java @@ -16,9 +16,6 @@ package org.springframework.restdocs.payload; -import java.util.HashMap; -import java.util.Map; - import org.springframework.restdocs.snippet.AbstractDescriptor; /** @@ -39,7 +36,12 @@ public class FieldDescriptor extends AbstractDescriptor { private String description; - FieldDescriptor(String path) { + /** + * Creates a new {@code FieldDescriptor} describing the field with the given + * {@code path}. + * @param path the path + */ + protected FieldDescriptor(String path) { this.path = path; } @@ -51,7 +53,7 @@ public class FieldDescriptor extends AbstractDescriptor { * @return {@code this} * @see JsonFieldType */ - public FieldDescriptor type(Object type) { + public final FieldDescriptor type(Object type) { this.type = type; return this; } @@ -61,7 +63,7 @@ public class FieldDescriptor extends AbstractDescriptor { * * @return {@code this} */ - public FieldDescriptor optional() { + public final FieldDescriptor optional() { this.optional = true; return this; } @@ -72,34 +74,45 @@ public class FieldDescriptor extends AbstractDescriptor { * @param description The field's description * @return {@code this} */ - public FieldDescriptor description(String description) { + public final FieldDescriptor description(String description) { this.description = description; return this; } - String getPath() { + /** + * Returns the path of the field described by this descriptor + * + * @return the path + */ + public final String getPath() { return this.path; } - Object getType() { + /** + * Returns the type of the field described by this descriptor + * + * @return the type + */ + public final Object getType() { return this.type; } - boolean isOptional() { + /** + * Returns {@code true} if the described field is optional, otherwise {@code false} + * + * @return {@code true} if the described field is optional, otherwise {@code false} + */ + public final boolean isOptional() { return this.optional; } - String getDescription() { + /** + * Returns the description for the field + * + * @return the field description + */ + public final String getDescription() { return this.description; } - Map toModel() { - Map model = new HashMap(); - model.put("path", this.path); - model.put("type", this.type.toString()); - model.put("description", this.description); - model.put("optional", this.optional); - model.putAll(this.getAttributes()); - return model; - } } diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java index 804fb591..be6d1ee8 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java @@ -67,7 +67,7 @@ public abstract class AbstractParametersSnippet extends TemplatedSnippet { Map model = new HashMap<>(); List> parameters = new ArrayList<>(); for (Entry entry : this.descriptorsByName.entrySet()) { - parameters.add(entry.getValue().toModel()); + parameters.add(createModelForDescriptor(entry.getValue())); } model.put("parameters", parameters); return model; @@ -105,4 +105,18 @@ public abstract class AbstractParametersSnippet extends TemplatedSnippet { return this.descriptorsByName; } + /** + * Returns a model for the given {@link descriptor}. + * + * @param descriptor the descriptor + * @return the model + */ + protected Map createModelForDescriptor(ParameterDescriptor descriptor) { + Map model = new HashMap<>(); + model.put("name", descriptor.getName()); + model.put("description", descriptor.getDescription()); + model.putAll(descriptor.getAttributes()); + return model; + } + } diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/ParameterDescriptor.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/ParameterDescriptor.java index 8edaf3cc..549500da 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/ParameterDescriptor.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/ParameterDescriptor.java @@ -16,9 +16,6 @@ package org.springframework.restdocs.request; -import java.util.HashMap; -import java.util.Map; - import org.springframework.restdocs.snippet.AbstractDescriptor; /** @@ -34,7 +31,13 @@ public class ParameterDescriptor extends AbstractDescriptor private String description; - ParameterDescriptor(String name) { + /** + * Creates a new {@code ParameterDescriptor} describing the parameter with the given + * {@code name}. + * + * @param name the name of the parameter + */ + protected ParameterDescriptor(String name) { this.name = name; } @@ -44,25 +47,27 @@ public class ParameterDescriptor extends AbstractDescriptor * @param description The parameter's description * @return {@code this} */ - public ParameterDescriptor description(String description) { + public final ParameterDescriptor description(String description) { this.description = description; return this; } - String getName() { + /** + * Returns the name of the parameter being described by this descriptor + * + * @return the name of the parameter + */ + public final String getName() { return this.name; } - String getDescription() { + /** + * Returns the description of the parameter + * + * @return the description + */ + public final String getDescription() { return this.description; } - Map toModel() { - Map model = new HashMap<>(); - model.put("name", this.name); - model.put("description", this.description); - model.putAll(getAttributes()); - return model; - } - } diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/AbstractDescriptor.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/AbstractDescriptor.java index 4766a171..931cd79e 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/AbstractDescriptor.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/AbstractDescriptor.java @@ -34,7 +34,7 @@ public abstract class AbstractDescriptor> { private Map attributes = new HashMap<>(); /** - * Sets the descriptor's attributes + * Adds the given {@code attributes} to the descriptor * * @param attributes the attributes * @return the descriptor @@ -52,7 +52,7 @@ public abstract class AbstractDescriptor> { * * @return the attributes */ - protected Map getAttributes() { + public final Map getAttributes() { return this.attributes; }