doc clarifications

projectnessie · May 10, 2023 · 6187611 · 6187611
1 parent c66ac49
commit 6187611
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 5 deletions.
diff --git a/api/model/src/main/java/org/projectnessie/api/v2/doc/ApiDoc.java b/api/model/src/main/java/org/projectnessie/api/v2/doc/ApiDoc.java
@@ -115,6 +115,12 @@ public interface ApiDoc {
 
   String KEY_PARAMETER_DESCRIPTION = "The key to a content object.\n\n" + KEY_ELEMENTS_DESCRIPTION;
 
+  String REQUESTED_KEY_PARAMETER_DESCRIPTION =
+      "Restrict the result to one or more keys.\n\n"
+          + "Can be combined with min/max-key and prefix-key parameters, however both predicates must match. "
+          + "This means that keys specified via this parameter that do not match a given min/max-key or prefix-key will not be returned.\n\n"
+          + KEY_ELEMENTS_DESCRIPTION;
+
   String KEY_MIN_PARAMETER_DESCRIPTION =
       "The lower bound of the content key range to retrieve (inclusive). "
           + "The content keys of all returned entries will be greater than or equal to the min-value.\n\n"
@@ -126,8 +132,9 @@ public interface ApiDoc {
           + KEY_ELEMENTS_DESCRIPTION;
 
   String KEY_PREFIX_PARAMETER_DESCRIPTION =
-      "The content key prefix to retrieve (inclusive). A content key matches a given prefix, if it starts with its value. "
+      "The content key prefix to retrieve (inclusive). A content key matches a given prefix, if it starts with the prefix value. "
           + "It is not restricted to key-element boundaries.\n\n"
+          + "Must not be combined with min/max-key parameters.\n\n"
           + KEY_ELEMENTS_DESCRIPTION;
 
   String DEFAULT_KEY_MERGE_MODE_DESCRIPTION =

diff --git a/api/model/src/main/java/org/projectnessie/api/v2/params/DiffParams.java b/api/model/src/main/java/org/projectnessie/api/v2/params/DiffParams.java
@@ -15,8 +15,8 @@
  */
 package org.projectnessie.api.v2.params;
 
-import static org.projectnessie.api.v2.doc.ApiDoc.KEY_PARAMETER_DESCRIPTION;
 import static org.projectnessie.api.v2.doc.ApiDoc.REF_PARAMETER_DESCRIPTION;
+import static org.projectnessie.api.v2.doc.ApiDoc.REQUESTED_KEY_PARAMETER_DESCRIPTION;
 
 import java.util.List;
 import javax.annotation.Nullable;
@@ -70,7 +70,7 @@ public class DiffParams extends KeyRangeParams<DiffParams> {
   @jakarta.ws.rs.PathParam("to-ref")
   private String toRef;
 
-  @Parameter(description = KEY_PARAMETER_DESCRIPTION)
+  @Parameter(description = REQUESTED_KEY_PARAMETER_DESCRIPTION)
   @QueryParam("key")
   @jakarta.ws.rs.QueryParam("key")
   private List<ContentKey> requestedKeys;

diff --git a/api/model/src/main/java/org/projectnessie/api/v2/params/EntriesParams.java b/api/model/src/main/java/org/projectnessie/api/v2/params/EntriesParams.java
@@ -15,7 +15,7 @@
  */
 package org.projectnessie.api.v2.params;
 
-import static org.projectnessie.api.v2.doc.ApiDoc.KEY_PARAMETER_DESCRIPTION;
+import static org.projectnessie.api.v2.doc.ApiDoc.REQUESTED_KEY_PARAMETER_DESCRIPTION;
 
 import java.util.List;
 import javax.annotation.Nullable;
@@ -34,7 +34,7 @@
  */
 public class EntriesParams extends KeyRangeParams<EntriesParams> {
 
-  @Parameter(description = KEY_PARAMETER_DESCRIPTION)
+  @Parameter(description = REQUESTED_KEY_PARAMETER_DESCRIPTION)
   @QueryParam("key")
   @jakarta.ws.rs.QueryParam("key")
   private List<ContentKey> requestedKeys;