feat: custom query key formatters (#1570)

* feature: Introduce support for custom URL query key formatters - Implements a key formatter for `camelCase` * docs: Adds querystrings examples * removes redundant code from `CamelCaseUrlParameterKeyFormatter.cs` * fix: restores binary-compability * Update after merge * chore: remove useless piece of code * feat(tests): CamelCaseUrlParameterKeyFormatter tests * feat(Tests): RefitSettings tests --------- Co-authored-by: Chris Pulman <chris.pulman@yahoo.com>
reactiveui · Jun 4, 2024 · 1b45219 · 1b45219
1 parent d85edef
commit 1b45219
Show file tree

Hide file tree

Showing 8 changed files with 3,089 additions and 4,095 deletions.
diff --git a/README.md b/README.md
@@ -39,9 +39,11 @@ services
 * [Where does this work?](#where-does-this-work)
   * [Breaking changes in 6.x](#breaking-changes-in-6x)
 * [API Attributes](#api-attributes)
-* [Dynamic Querystring Parameters](#dynamic-querystring-parameters)
-* [Collections as Querystring parameters](#collections-as-querystring-parameters)
-* [Unescape Querystring parameters](#unescape-querystring-parameters)
+* [Querystrings](#querystrings)
+  * [Dynamic Querystring Parameters](#dynamic-querystring-parameters)
+  * [Collections as Querystring parameters](#collections-as-querystring-parameters)
+  * [Unescape Querystring parameters](#unescape-querystring-parameters)
+  * [Custom Querystring Parameter formatting](#custom-querystring-parameter-formatting)
 * [Body content](#body-content)
   * [Buffering and the Content-Length header](#buffering-and-the-content-length-header)
   * [JSON content](#json-content)
@@ -175,7 +177,9 @@ Search("admin/products");
 >>> "/search/admin/products"
 ```
 
-### Dynamic Querystring Parameters
+### Querystrings
+
+#### Dynamic Querystring Parameters
 
 If you specify an `object` as a query parameter, all public properties which are not null are used as query parameters.
 This previously only applied to GET requests, but has now been expanded to all HTTP request methods, partly thanks to Twitter's hybrid API that insists on non-GET requests with querystring parameters.
@@ -229,7 +233,7 @@ Task<Tweet> PostTweet([Query]TweetParams params);
 
 Where `TweetParams` is a POCO, and properties will also support `[AliasAs]` attributes.
 
-### Collections as Querystring parameters
+#### Collections as Querystring parameters
 
 Use the `Query` attribute to specify format in which collections should be formatted in query string
 
@@ -256,7 +260,7 @@ var gitHubApi = RestService.For<IGitHubApi>("https://api.github.com",
     });
 ```
 
-### Unescape Querystring parameters
+#### Unescape Querystring parameters
 
 Use the `QueryUriFormat` attribute to specify if the query parameters should be url escaped
 
@@ -269,6 +273,130 @@ Query("Select+Id,Name+From+Account")
 >>> "/query?q=Select+Id,Name+From+Account"
 ```
 
+#### Custom Querystring parameter formatting
+
+**Formatting Keys**
+
+To customize the format of query keys, you have two main options:
+
+1. **Using the `AliasAs` Attribute**:
+
+   You can use the `AliasAs` attribute to specify a custom key name for a property. This attribute will always take precedence over any key formatter you specify.
+
+   ```csharp
+   public class MyQueryParams
+   {
+       [AliasAs("order")]
+       public string SortOrder { get; set; }
+
+       public int Limit { get; set; }
+   }
+
+   [Get("/group/{id}/users")]
+   Task<List<User>> GroupList([AliasAs("id")] int groupId, [Query] MyQueryParams params);
+
+   params.SortOrder = "desc";
+   params.Limit = 10;
+
+   GroupList(1, params);
+   ```
+
+   This will generate the following request:
+
+   ```
+   /group/1/users?order=desc&Limit=10
+   ```
+
+2. **Using the `RefitSettings.UrlParameterKeyFormatter` Property**:
+
+   By default, Refit uses the property name as the query key without any additional formatting. If you want to apply a custom format across all your query keys, you can use the `UrlParameterKeyFormatter` property. Remember that if a property has an `AliasAs` attribute, it will be used regardless of the formatter.
+
+   The following example uses the built-in `CamelCaseUrlParameterKeyFormatter`:
+
+   ```csharp
+   public class MyQueryParams
+   {
+       public string SortOrder { get; set; }
+
+       [AliasAs("queryLimit")]
+       public int Limit { get; set; }
+   }
+
+   [Get("/group/users")]
+   Task<List<User>> GroupList([Query] MyQueryParams params);
+
+   params.SortOrder = "desc";
+   params.Limit = 10;
+   ```
+
+   The request will look like:
+
+   ```
+   /group/users?sortOrder=desc&queryLimit=10
+   ```
+
+**Note**: The `AliasAs` attribute always takes the top priority. If both the attribute and a custom key formatter are present, the `AliasAs` attribute's value will be used.
+
+#### Formatting URL Parameter Values with the `UrlParameterFormatter`
+
+In Refit, the `UrlParameterFormatter` property within `RefitSettings` allows you to customize how parameter values are formatted in the URL. This can be particularly useful when you need to format dates, numbers, or other types in a specific manner that aligns with your API's expectations.
+
+**Using `UrlParameterFormatter`**:
+
+Assign a custom formatter that implements the `IUrlParameterFormatter` interface to the `UrlParameterFormatter` property.
+
+```csharp
+public class CustomDateUrlParameterFormatter : IUrlParameterFormatter
+{
+    public string? Format(object? value, ICustomAttributeProvider attributeProvider, Type type)
+    {
+        if (value is DateTime dt)
+        {
+            return dt.ToString("yyyyMMdd");
+        }
+
+        return value?.ToString();
+    }
+}
+
+var settings = new RefitSettings
+{
+    UrlParameterFormatter = new CustomDateUrlParameterFormatter()
+};
+```
+
+In this example, a custom formatter is created for date values. Whenever a `DateTime` parameter is encountered, it formats the date as `yyyyMMdd`.
+
+**Formatting Dictionary Keys**:
+
+When dealing with dictionaries, it's important to note that keys are treated as values. If you need custom formatting for dictionary keys, you should use the `UrlParameterFormatter` as well.
+
+For instance, if you have a dictionary parameter and you want to format its keys in a specific way, you can handle that in the custom formatter:
+
+```csharp
+public class CustomDictionaryKeyFormatter : IUrlParameterFormatter
+{
+    public string? Format(object? value, ICustomAttributeProvider attributeProvider, Type type)
+    {
+        // Handle dictionary keys
+        if (attributeProvider is PropertyInfo prop && prop.PropertyType.IsGenericType && prop.PropertyType.GetGenericTypeDefinition() == typeof(Dictionary<,>))
+        {
+            // Custom formatting logic for dictionary keys
+            return value?.ToString().ToUpperInvariant();
+        }
+
+        return value?.ToString();
+    }
+}
+
+var settings = new RefitSettings
+{
+    UrlParameterFormatter = new CustomDictionaryKeyFormatter()
+};
+```
+
+In the above example, the dictionary keys will be converted to uppercase.
+
 ### Body content
 
 One of the parameters in your method can be used as the body, by using the

diff --git a/Refit.Newtonsoft.Json/Refit.Newtonsoft.Json.csproj b/Refit.Newtonsoft.Json/Refit.Newtonsoft.Json.csproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <Product>Refit Serializer for Newtonsoft.Json ($(TargetFramework))</Product>
     <Description>Refit Serializers for Newtonsoft.Json</Description>
-    <TargetFrameworks>net462;netstandard2.0;net6.0;net7.0;net8.0</TargetFrameworks>
+    <TargetFrameworks>net462;netstandard2.0;net6.0;net8.0</TargetFrameworks>
     <GenerateDocumentationFile Condition=" '$(Configuration)' == 'Release' ">true</GenerateDocumentationFile>
     <RootNamespace>Refit</RootNamespace>
     <Nullable>enable</Nullable>

diff --git a/Refit.Tests/CamelCaseUrlParameterKeyFormatter.cs b/Refit.Tests/CamelCaseUrlParameterKeyFormatter.cs
@@ -0,0 +1,42 @@
+using Xunit;
+
+namespace Refit.Tests;
+
+public class CamelCaselTestsRequest
+{
+    public string alreadyCamelCased { get; set; }
+    public string NOTCAMELCased { get; set; }
+}
+
+public class CamelCaseUrlParameterKeyFormatterTests
+{
+    [Fact]
+    public void Format_EmptyKey_ReturnsEmptyKey()
+    {
+        var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();
+
+        var output = urlParameterKeyFormatter.Format(string.Empty);
+        Assert.Equal(string.Empty, output);
+    }
+
+    [Fact]
+    public void FormatKey_Returns_ExpectedValue()
+    {
+        var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();
+
+        var refitSettings = new RefitSettings { UrlParameterKeyFormatter = urlParameterKeyFormatter };
+        var fixture = new RequestBuilderImplementation<IDummyHttpApi>(refitSettings);
+        var factory = fixture.BuildRequestFactoryForMethod(nameof(IDummyHttpApi.ComplexQueryObjectWithDictionary));
+
+        var complexQuery = new CamelCaselTestsRequest
+        {
+            alreadyCamelCased = "value1",
+            NOTCAMELCased = "value2"
+        };
+
+        var output = factory([complexQuery]);
+        var uri = new Uri(new Uri("http://api"), output.RequestUri);
+
+        Assert.Equal("/foo?alreadyCamelCased=value1&notcamelCased=value2", uri.PathAndQuery);
+    }
+}
diff --git a/Refit.Tests/RefitSettings.cs b/Refit.Tests/RefitSettings.cs
@@ -0,0 +1,30 @@
+using Xunit;
+
+namespace Refit.Tests;
+
+public class RefitSettingsTests
+{
+    [Fact]
+    public void Can_CreateRefitSettings_WithoutException()
+    {
+        var contentSerializer = new NewtonsoftJsonContentSerializer();
+        var urlParameterFormatter = new DefaultUrlParameterFormatter();
+        var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();
+        var formUrlEncodedParameterFormatter = new DefaultFormUrlEncodedParameterFormatter();
+
+        var exception = Record.Exception(() => new RefitSettings());
+        Assert.Null(exception);
+
+        exception = Record.Exception(() => new RefitSettings(contentSerializer));
+        Assert.Null(exception);
+
+        exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter));
+        Assert.Null(exception);
+
+        exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter, formUrlEncodedParameterFormatter));
+        Assert.Null(exception);
+
+        exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter, formUrlEncodedParameterFormatter, urlParameterKeyFormatter));
+        Assert.Null(exception);
+    }
+}