Add parameter annotation @tag for setting request tags

retrofit/src/main/java/retrofit2/ParameterHandler.java

@@ -400,4 +400,16 @@ static final class Body<T> extends ParameterHandler<T> {
       builder.setBody(body);
     }
   }
+
+  static final class Tag<T> extends ParameterHandler<T> {
+    final Class<T> cls;
+
+    Tag(Class<T> cls) {
+      this.cls = cls;
+    }
+
+    @Override void apply(RequestBuilder builder, @Nullable T value) {
+      builder.addTag(cls, value);
+    }
+  }
 }

retrofit/src/main/java/retrofit2/RequestBuilder.java

@@ -208,6 +208,10 @@ void setBody(RequestBody body) {
     this.body = body;
   }
 
+  <T> void addTag(Class<T> cls, @Nullable T value) {
+    requestBuilder.tag(cls, value);
+  }
+
   Request.Builder get() {
     HttpUrl url;
     HttpUrl.Builder urlBuilder = this.urlBuilder;

retrofit/src/main/java/retrofit2/RequestFactory.java

@@ -55,6 +55,7 @@
 import retrofit2.http.Query;
 import retrofit2.http.QueryMap;
 import retrofit2.http.QueryName;
+import retrofit2.http.Tag;
 import retrofit2.http.Url;
 
 import static retrofit2.Utils.methodError;
@@ -712,6 +713,24 @@ private ParameterHandler<?> parseParameterAnnotation(
         }
         gotBody = true;
         return new ParameterHandler.Body<>(method, p, converter);
+
+      } else if (annotation instanceof Tag) {
+        validateResolvableType(p, type);
+
+        Class<?> tagType = Utils.getRawType(type);
+        for (int i = p - 1; i >= 0; i--) {
+          ParameterHandler<?> otherHandler = parameterHandlers[i];
+          if (otherHandler instanceof ParameterHandler.Tag
+              && ((ParameterHandler.Tag) otherHandler).cls.equals(tagType)) {
+            throw parameterError(method, p, "@Tag type "
+                + tagType.getName()
+                + " is duplicate of parameter #"
+                + (i + 1)
+                + " and would always overwrite its value.");
+          }
+        }
+
+        return new ParameterHandler.Tag<>(tagType);
       }
 
       return null; // Not a Retrofit annotation.

retrofit/src/main/java/retrofit2/http/Tag.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2019 Square, Inc.
+ *
+ * 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.
+ */
+package retrofit2.http;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Adds the argument instance as a request tag using the type as the key.
+ * <pre><code>
+ * &#64;GET("/")
+ * Call&lt;ResponseBody&gt; foo(@Tag String tag);
+ * </code></pre>
+ * Tag arguments may be {@code null} which will omit them from the request. Passing a parameterized
+ * type such as {@code List<String>} will use the raw type (i.e., {@code List.class}) as the key.
+ * Duplicate tag types are not allowed.
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+public @interface Tag {
+}

retrofit/src/test/java/retrofit2/RequestFactoryTest.java

@@ -57,8 +57,10 @@
 import retrofit2.http.Query;
 import retrofit2.http.QueryMap;
 import retrofit2.http.QueryName;
+import retrofit2.http.Tag;
 import retrofit2.http.Url;
 
+import static java.util.Collections.emptyList;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.fail;
@@ -2250,7 +2252,7 @@ Call<ResponseBody> method(@PartMap List<Object> parts) {
     }
 
     try {
-      buildRequest(Example.class, Collections.emptyList());
+      buildRequest(Example.class, emptyList());
       fail();
     } catch (IllegalArgumentException e) {
       assertThat(e).hasMessage(
@@ -2877,6 +2879,63 @@ class Example {
     }
   }
 
+  @Test public void tag() {
+    class Example {
+      @GET("/") Call<ResponseBody> method(@Tag String tag) {
+        return null;
+      }
+    }
+
+    Request request = buildRequest(Example.class, "tagValue");
+    assertThat(request.tag(String.class)).isEqualTo("tagValue");
+  }
+
+  @Test public void tagGeneric() {
+    class Example {
+      @GET("/") Call<ResponseBody> method(@Tag List<String> tag) {
+        return null;
+      }
+    }
+
+    List<String> strings = Arrays.asList("tag", "value");
+    Request request = buildRequest(Example.class, strings);
+    assertThat(request.tag(List.class)).isSameAs(strings);
+  }
+
+  @Test public void tagDuplicateFails() {
+    class Example {
+      @GET("/") Call<ResponseBody> method(@Tag String one, @Tag String two) {
+        return null;
+      }
+    }
+
+    try {
+      buildRequest(Example.class, "one", "two");
+      fail();
+    } catch (IllegalArgumentException e) {
+      assertThat(e).hasMessage(
+          "@Tag type java.lang.String is duplicate of parameter #1 and would always overwrite its value. (parameter #2)\n"
+              + "    for method Example.method");
+    }
+  }
+
+  @Test public void tagGenericDuplicateFails() {
+    class Example {
+      @GET("/") Call<ResponseBody> method(@Tag List<String> one, @Tag List<Long> two) {
+        return null;
+      }
+    }
+
+    try {
+      buildRequest(Example.class, emptyList(), emptyList());
+      fail();
+    } catch (IllegalArgumentException e) {
+      assertThat(e).hasMessage(
+          "@Tag type java.util.List is duplicate of parameter #1 and would always overwrite its value. (parameter #2)\n"
+              + "    for method Example.method");
+    }
+  }
+
   private static void assertBody(RequestBody body, String expected) {
     assertThat(body).isNotNull();
     Buffer buffer = new Buffer();