Merge pull request #466 from christianhelle/polymorphic-serialization…

…-docs Add basic documentation for Polymorphic Serialization
christianhelle · Sep 12, 2024 · 089e189 · 089e189
2 parents 75d43fc + b165b75
commit 089e189
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -111,13 +111,14 @@ OPTIONS:
                                                                  - SingleClientFromPathSegments                                                                                                            
                                                                  See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html for more information                                    
         --immutable-records                                      Generate contracts as immutable records instead of classes                                                                                
-        --use-apizr                                              Set to true to use Apizr by:                                                                                                              
+        --use-apizr                                              Use Apizr by:                                                                                                                             
                                                                  - Adding a final IApizrRequestOptions options parameter to all generated methods                                                          
                                                                  - Providing cancellation tokens by Apizr request options instead of a dedicated parameter                                                 
                                                                  - Using method overloads instead of optional parameters                                                                                   
                                                                  See https://refitter.github.io for more information and https://www.apizr.net to get started with Apizr                                   
-        --use-dynamic-querystring-parameters                     Set to <c>true</c> to wrap multiple query parameters into a single complex one. Default is <c>false</c> (no wrapping).                    
+        --use-dynamic-querystring-parameters                     Enable wrapping multiple query parameters into a single complex one. Default is no wrapping.                                              
                                                                  See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information                            
+        --use-polymorphic-serialization                          Use System.Text.Json polymorphic serialization                                                                                            
 ```
 
 To generate code from an OpenAPI specifications file, run the following:
@@ -208,6 +209,7 @@ The following is an example `.refitter` file
   "operationNameGenerator": "Default", // Optional. May be one of Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments
   "immutableRecords": false,
   "useDynamicQuerystringParameters": true, // Optional. Default=false
+  "usePolymorphicSerialization", false, // Optional. Default=false
   "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional

diff --git a/docs/docfx_project/articles/refitter-file-format.md b/docs/docfx_project/articles/refitter-file-format.md
@@ -61,6 +61,7 @@ The following is an example `.refitter` file
   "operationNameGenerator": "Default", // Optional. May be one of Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments
   "immutableRecords": false,
   "useDynamicQuerystringParameters": false, // Optional. Default=false
+  "usePolymorphicSerialization", false, // Optional. Default=false
   "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional
@@ -153,6 +154,7 @@ The following is an example `.refitter` file
 - `operationNameGenerator`: The NSwag `IOperationNameGenerator` implementation to use. See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html
 - `immutableRecords`: Set to `true` to generate contracts as immutable records instead of classes. Default is `false`
 - `useDynamicQuerystringParameters`: Set to `true` to wrap multiple query parameters into a single complex one. Default is `false` (no wrapping). See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information.
+- `usePolymorphicSerialization`: Set to `true` to use `System.Text.Json` polymorphic serialization.
 - `generateMultipleFiles`: Set to `true` to generate multiple files. This is automatically set to `true` when `ContractsOutputFolder` is specified. Refit interface(s) are written to a file called `RefitInterfaces.cs`, Contracts are written to a file called `Contracts.cs`, and Dependency Injection is written to a file called `DependencyInjection.cs`
 - `dependencyInjectionSettings` - Setting this will generated extension methods to `IServiceCollection` for configuring Refit clients
   - `baseUrl` - Used as the HttpClient base address. Leave this blank to manually set the base URL
@@ -367,6 +369,10 @@ The following is an example `.refitter` file
             "type": "boolean",
             "description": "Set to true to wrap multiple query parameters into a single complex one."
         },
+        "usePolymorphicSerialization": {
+            "type": "boolean",
+            "description": "Set to true to use System.Text.Json polymorphic serialization"
+        },
         "generateMultipleFiles": {
             "type": "boolean",
             "description": "Set to `true` to generate multiple files. This is automatically set to `true` when `ContractsOutputFolder` is specified. Refit interface(s) are written to a file called `RefitInterfaces.cs`, Contracts are written to a file called `Contracts.cs`, and Dependency Injection is written to a file called `DependencyInjection.cs`"

diff --git a/src/Refitter/README.md b/src/Refitter/README.md
@@ -96,6 +96,7 @@ OPTIONS:
                                                                     See https://refitter.github.io for more information and https://www.apizr.net to get started with Apizr                                                                               
         --use-dynamic-querystring-parameters                        Wrap multiple query parameters into a single complex one.
                                                                     See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information.
+        --use-polymorphic-serialization                             Use System.Text.Json polymorphic serialization
 ```
 
 ### .Refitter File format
@@ -156,6 +157,7 @@ The following is an example `.refitter` file
   "operationNameGenerator": "Default", // Optional. May be one of Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments
   "immutableRecords": false,
   "useDynamicQuerystringParameters": true, // Optional. Default=false
+  "usePolymorphicSerialization" true, // Optional. Default=false
   "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional
@@ -243,6 +245,7 @@ The following is an example `.refitter` file
 - `operationNameGenerator`: The NSwag `IOperationNameGenerator` implementation to use. See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html
 - `immutableRecords`: Set to `true` to generate contracts as immutable records instead of classes. Default is `false`
 - `useDynamicQuerystringParameters`: Set to `true` to wrap multiple query parameters into a single complex one. Default is `false` (no wrapping). See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information.
+- `usePolymorphicSerialization`: Set to `true` to use `System.Text.Json` polymorphic serialization.
 - `dependencyInjectionSettings` - Setting this will generated extension methods to `IServiceCollection` for configuring Refit clients
   - `baseUrl` - Used as the HttpClient base address. Leave this blank to manually set the base URL
   - `httpMessageHandlers` - A collection of `HttpMessageHandler` that is added to the HttpClient pipeline

diff --git a/src/Refitter/Settings.cs b/src/Refitter/Settings.cs
@@ -193,7 +193,7 @@ The NSwag IOperationNameGenerator implementation to use.
     public bool ImmutableRecords { get; set; }
 
     [Description("""
-                 Set to true to use Apizr by:
+                 Use Apizr by:
                  - Adding a final IApizrRequestOptions options parameter to all generated methods
                  - Providing cancellation tokens by Apizr request options instead of a dedicated parameter
                  - Using method overloads instead of optional parameters
@@ -204,14 +204,14 @@ The NSwag IOperationNameGenerator implementation to use.
     public bool UseApizr { get; set; }
 
     [Description("""
-                 Set to <c>true</c> to wrap multiple query parameters into a single complex one. Default is <c>false</c> (no wrapping).
+                 Enable wrapping multiple query parameters into a single complex one. Default is no wrapping.
                  See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information.
                  """)]
     [CommandOption("--use-dynamic-querystring-parameters")]
     [DefaultValue(false)]
     public bool UseDynamicQuerystringParameters { get; set; }
 
-    [Description("Set to <c>true</c> to use System.Text.Json polymorphic serialization.")]
+    [Description("Use System.Text.Json polymorphic serialization.")]
     [CommandOption("--use-polymorphic-serialization")]
     [DefaultValue(false)]
     public bool UsePolymorphicSerialization { get; set; }