Added conditional builder methods

dilipkrish · dilipkrish · commit 406f711e5bc3 · 2020-07-09T11:02:10.000-05:00
Also polished the javadocs as the APIs have become firm

(2613)
diff --git a/springfox-core/src/main/java/springfox/documentation/builders/CompoundModelSpecificationBuilder.java b/springfox-core/src/main/java/springfox/documentation/builders/CompoundModelSpecificationBuilder.java
@@ -1,5 +1,7 @@
 package springfox.documentation.builders;
 
+import org.springframework.lang.NonNull;
+import org.springframework.lang.NonNullApi;
 import springfox.documentation.schema.CompoundModelSpecification;
 import springfox.documentation.schema.ModelKeyBuilder;
 import springfox.documentation.schema.PropertySpecification;
@@ -26,26 +28,66 @@ private PropertySpecificationBuilder propertyBuilder(String name) {
     return properties.computeIfAbsent(name, PropertySpecificationBuilder::new);
   }
 
-  public Function<Consumer<PropertySpecificationBuilder>, CompoundModelSpecificationBuilder> property(String name) {
+  /**
+   * Provides method to create a property with given name
+   * @param name - name of the property to create
+   * @return returns a function that that provides a consumer for building a property
+   */
+  public Function<Consumer<PropertySpecificationBuilder>, CompoundModelSpecificationBuilder> property(
+      @NonNull String name) {
     return property -> {
       property.accept(propertyBuilder(name));
       return this;
     };
   }
+  
+  /**
+   * Provides method to maybe create a property with given name. If the property doesnt exist the consumer is a no-op.
+   * Whatever we build downstream when the property doesnt exist is thrown away.
+   * @param name - name of the property to create
+   * @return returns a function that that provides a consumer for building a property
+   */
+  public Function<Consumer<PropertySpecificationBuilder>, CompoundModelSpecificationBuilder> propertyIfExists(
+      @NonNull String name) {
+    return property -> {
+      if (properties.containsKey(name)) {
+        property.accept(propertyBuilder(name));
+      } else {
+        PropertySpecificationBuilder throwAwayBuilder = new PropertySpecificationBuilder(name);
+        property.accept(throwAwayBuilder);
+      }
+      return this;
+    };
+  }
 
-  public CompoundModelSpecificationBuilder modelKey(Consumer<ModelKeyBuilder> consumer) {
+  /**
+   * Provides a fluent builder consumer for building a model key
+   * @param consumer - builder consumer
+   * @return this
+   */
+  public CompoundModelSpecificationBuilder modelKey(@NonNull Consumer<ModelKeyBuilder> consumer) {
     if (modelKey == null) {
       this.modelKey = new ModelKeyBuilder();
     }
     consumer.accept(modelKey);
     return this;
   }
 
+  /**
+   * Provides override for the max properties. It uses the number of actual properties when not provided.
+   * @param maxProperties - maximum properties that need to be set
+   * @return this
+   */
   public CompoundModelSpecificationBuilder maxProperties(Integer maxProperties) {
     this.maxProperties = maxProperties;
     return this;
   }
 
+  /**
+   * Provides override for the min properties. It uses the number of actual properties when not provided.
+   * @param minProperties - minimum properties that need to be set
+   * @return this
+   */
   public CompoundModelSpecificationBuilder minProperties(Integer minProperties) {
     this.minProperties = minProperties;
     return this;
@@ -54,19 +96,26 @@ public CompoundModelSpecificationBuilder minProperties(Integer minProperties) {
   public CompoundModelSpecification build() {
     List<PropertySpecification> properties = this.properties.values().stream()
         .map(PropertySpecificationBuilder::build)
+        .filter(prop -> !prop.getHidden())
         .collect(Collectors.toList());
     if (modelKey != null) {
       return new CompoundModelSpecification(
           modelKey.build(),
           properties,
-          maxProperties,
-          minProperties,
+          maxProperties == null ? properties.size() : maxProperties,
+          minProperties == null ? properties.size() : minProperties,
           discriminator,
           subclassReferences);
     }
     return null;
   }
 
+
+  /**
+   * Copies from an existing model
+   * @param other - other model to copy from
+   * @return this
+   */
   public CompoundModelSpecificationBuilder copyOf(CompoundModelSpecification other) {
     if (other == null) {
       return this;
@@ -79,6 +128,11 @@ public CompoundModelSpecificationBuilder copyOf(CompoundModelSpecification other
         .subclassReferences(other.getSubclassReferences());
   }
 
+  /**
+   * Copies existing set of properties
+   * @param properties - properties to copy from
+   * @return this
+   */
   public CompoundModelSpecificationBuilder properties(Collection<PropertySpecification> properties) {
     properties.forEach(each -> this.property(each.getName())
         .apply(p -> {
@@ -103,11 +157,21 @@ public CompoundModelSpecificationBuilder properties(Collection<PropertySpecifica
     return this;
   }
 
+  /**
+   * Inheritance discriminator
+   * @param discriminator - property to discriminate on
+   * @return this
+   */
   public CompoundModelSpecificationBuilder discriminator(String discriminator) {
     this.discriminator = discriminator;
     return this;
   }
 
+  /**
+   * References to subclasses
+   * @param subclassReferences - the reference specifications of subclasses
+   * @return this
+   */
   public CompoundModelSpecificationBuilder subclassReferences(
       Collection<ReferenceModelSpecification> subclassReferences) {
     this.subclassReferences.addAll(subclassReferences);
diff --git a/springfox-core/src/main/java/springfox/documentation/builders/ModelSpecificationBuilder.java b/springfox-core/src/main/java/springfox/documentation/builders/ModelSpecificationBuilder.java
@@ -1,6 +1,8 @@
 package springfox.documentation.builders;
 
 import org.springframework.lang.NonNull;
+import org.springframework.lang.Nullable;
+import springfox.documentation.annotations.Incubating;
 import springfox.documentation.schema.CollectionSpecification;
 import springfox.documentation.schema.CompoundModelSpecification;
 import springfox.documentation.schema.MapSpecification;
@@ -15,6 +17,7 @@
 import java.util.function.Consumer;
 import java.util.stream.Stream;
 
+import static springfox.documentation.builders.BuilderDefaults.*;
 import static springfox.documentation.builders.NoopValidator.*;
 
 public class ModelSpecificationBuilder {
@@ -27,11 +30,21 @@ public class ModelSpecificationBuilder {
   private CompoundModelSpecificationBuilder compoundModelBuilder;
   private final Validator<ModelSpecificationBuilder> validator = this::validateSpecification;
 
-  public ModelSpecificationBuilder name(String name) {
-    this.name = name;
+  /**
+   * Updates the name of the model
+   * @param name - Name of the model
+   * @return this
+   */
+  public ModelSpecificationBuilder name(@NonNull String name) {
+    this.name = defaultIfAbsent(name, this.name);
     return this;
   }
 
+  /**
+   * Provides a consumer to build facets
+   * @param facets - consumer that facilitates building a facet
+   * @return this
+   */
   public ModelSpecificationBuilder facets(@NonNull Consumer<ModelFacetsBuilder> facets) {
     if (facetsBuilder == null) {
       facetsBuilder = new ModelFacetsBuilder();
@@ -40,6 +53,11 @@ public ModelSpecificationBuilder facets(@NonNull Consumer<ModelFacetsBuilder> fa
     return this;
   }
 
+  /**
+   * Updates the scalar type
+   * @param type - scalar type
+   * @return this
+   */
   public ModelSpecificationBuilder scalarModel(ScalarType type) {
     if (type != null) {
       this.scalar = new ScalarModelSpecification(type);
@@ -54,37 +72,121 @@ private CompoundModelSpecificationBuilder compoundModelBuilder() {
     return compoundModelBuilder;
   }
 
+  /**
+   * Provides a consumer to help building a compound model
+   * @param compound - consumer that facilitates building a compound model
+   * @return this
+   */
   public ModelSpecificationBuilder compoundModel(@NonNull Consumer<CompoundModelSpecificationBuilder> compound) {
     compound.accept(compoundModelBuilder());
     return this;
   }
 
+  /**
+   * Provides a consumer to help build a compound model if one already exists. If the model is a different type,
+   * then any operations done with the help of the consumer will be a no-op
+   * @param compound consumer that facilitates building a compound model
+   * @return this
+   */
+  public ModelSpecificationBuilder compoundModelIfExists(
+      @NonNull Consumer<CompoundModelSpecificationBuilder> compound) {
+    if (compoundModelBuilder != null) {
+      compound.accept(compoundModelBuilder);
+    } else {
+      CompoundModelSpecificationBuilder throwAwayBuilder = new CompoundModelSpecificationBuilder();
+      compound.accept(throwAwayBuilder);
+    }
+    return this;
+  }
+
+  /**
+   * Provides a consumer to build the collection model
+   * @param consumer consumer that facilitates building a collection
+   * @return this
+   */
   public ModelSpecificationBuilder collectionModel(@NonNull Consumer<CollectionSpecificationBuilder> consumer) {
     consumer.accept(collectionBuilder());
     return this;
   }
 
+  /**
+   * Conditionally provides a consumer to build the colleciton model. If the model is a different type,
+   *    then any operations done with the help of the consumer will be a no-op
+   * @param consumer consumer that facilitates building a collection
+   * @return this
+   */
+  public ModelSpecificationBuilder collectionModelIfExists(
+      @NonNull Consumer<CollectionSpecificationBuilder> consumer) {
+    if (collection != null) {
+      consumer.accept(collection);
+    } else {
+      CollectionSpecificationBuilder throwAwayBuilder = new CollectionSpecificationBuilder();
+      consumer.accept(throwAwayBuilder);
+    }
+    return this;
+  }
+
   private CollectionSpecificationBuilder collectionBuilder() {
     if (collection == null) {
       collection = new CollectionSpecificationBuilder();
     }
     return collection;
   }
 
+  /**
+   * Provides a consumer to build the map model.
+   * @param consumer consumer that facilitates building a map
+   * @return this
+   */
   public ModelSpecificationBuilder mapModel(@NonNull Consumer<MapSpecificationBuilder> consumer) {
     consumer.accept(mapBuilder());
     return this;
   }
 
+  /**
+   * Conditionally provides a consumer to build the map model.
+   * @param consumer consumer that facilitates building a map
+   * @return this
+   */
+  public ModelSpecificationBuilder mapModelIfExists(@NonNull Consumer<MapSpecificationBuilder> consumer) {
+    if (map != null) {
+      consumer.accept(map);
+    } else {
+      MapSpecificationBuilder throwAwayBuilder = new MapSpecificationBuilder();
+      consumer.accept(throwAwayBuilder);
+    }
+    return this;
+  }
+
   private MapSpecificationBuilder mapBuilder() {
     if (map == null) {
       map = new MapSpecificationBuilder();
     }
     return map;
   }
 
-  public ModelSpecificationBuilder referenceModel(Consumer<ReferenceModelSpecificationBuilder> modelKey) {
-    modelKey.accept(referenceModelBuilder());
+  /**
+   * Provides a consumer to build the reference model.
+   * @param consumer consumer that facilitates building a reference model
+   * @return this
+   */
+  public ModelSpecificationBuilder referenceModel(Consumer<ReferenceModelSpecificationBuilder> consumer) {
+    consumer.accept(referenceModelBuilder());
+    return this;
+  }
+
+  /**
+   * Provides a consumer to build the reference model.
+   * @param consumer consumer that facilitates building a reference model
+   * @return this
+   */
+  public ModelSpecificationBuilder referenceModelIfExists(Consumer<ReferenceModelSpecificationBuilder> consumer) {
+    if (referenceModel != null) {
+      consumer.accept(referenceModel);
+    } else {
+      ReferenceModelSpecificationBuilder throwAwayBuilder = new ReferenceModelSpecificationBuilder();
+      consumer.accept(throwAwayBuilder);
+    }
     return this;
   }
 
@@ -112,7 +214,12 @@ public ModelSpecification build() {
         referenceModel != null ? referenceModel.build() : null);
   }
 
-  public ModelSpecificationBuilder copyOf(ModelSpecification other) {
+  /**
+   * Copies from an other model
+   * @param other the other model
+   * @return this
+   */
+  public ModelSpecificationBuilder copyOf(@Nullable ModelSpecification other) {
     if (other != null) {
       ScalarType scalar = other.getScalar()
           .map(ScalarModelSpecification::getType)
@@ -180,6 +287,12 @@ private Object safeReferenceBuild() {
     return referenceModel != null ? referenceModel.build() : null;
   }
 
+  /**
+   * This is an experimental API. May be removed/modified
+   * @param scalar - scalar to replace the models with
+   * @return this
+   */
+  @Incubating("3.0.0")
   public ModelSpecificationBuilder maybeConvertToScalar(ScalarType scalar) {
     scalarModel(scalar);
     if (compoundModelBuilder != null) {
