Add IDisposable client generation info to docs

christianhelle · Nov 26, 2024 · 515f15e · 515f15e
1 parent 1fc523b
commit 515f15e
Show file tree

Hide file tree

Showing 6 changed files with 94 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -119,7 +119,12 @@ OPTIONS:
                                                                  See https://refitter.github.io for more information and https://www.apizr.net to get started with Apizr                                   
         --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                                                                                            
+        --use-polymorphic-serialization                          Use System.Text.Json polymorphic serialization.                                                                                           
+                                                                 Replaces NSwag JsonInheritanceConverter attributes with System.Text.Json JsonPolymorphicAttributes.                                       
+                                                                 To have the native support of inheritance (de)serialization and fallback to base types when                                               
+                                                                 payloads with (yet) unknown types are offered by newer versions of an API                                                                 
+                                                                 See https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism for more information                    
+        --disposable                                             Generate refit clients that implement IDisposable                                                                                         
 ```
 
 To generate code from an OpenAPI specifications file, run the following:
@@ -210,7 +215,8 @@ 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
+  "usePolymorphicSerialization": true, // Optional. Default=false
+  "generateDisposableClients": 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

diff --git a/docs/docfx_project/articles/cli-tool.md b/docs/docfx_project/articles/cli-tool.md
@@ -93,16 +93,19 @@ 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).                    
-                                                                 See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information
-        --use-polymorphic-serialization                          Replaces NSwag JsonInheritanceConverter attributes with System.Text.Json JsonPolymorphicAttributes. To have the native support of inheritance (de)serialization and fallback to base types when payloads with (yet) unknown types are offered by newer versions of an API.
-                                                                 See https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism for more information
-
+        --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.                                                                                           
+                                                                 Replaces NSwag JsonInheritanceConverter attributes with System.Text.Json JsonPolymorphicAttributes.                                       
+                                                                 To have the native support of inheritance (de)serialization and fallback to base types when                                               
+                                                                 payloads with (yet) unknown types are offered by newer versions of an API                                                                 
+                                                                 See https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism for more information                    
+        --disposable                                             Generate refit clients that implement IDisposable                                                                                         
 ```
 
 To generate code from an OpenAPI specifications file, run the following:

diff --git a/docs/docfx_project/articles/refitter-file-format.md b/docs/docfx_project/articles/refitter-file-format.md
@@ -61,7 +61,8 @@ 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
+  "usePolymorphicSerialization": true, // Optional. Default=false
+  "generateDisposableClients": 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

diff --git a/docs/json-schema.json b/docs/json-schema.json
@@ -157,6 +157,14 @@
         "type": "boolean",
         "description": "Set to `true` to generate multiple files. 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`"
     },
+    "usePolymorphicSerialization": {
+      "type": "boolean",
+      "description": "Use System.Text.Json polymorphic serialization. Replaces NSwag JsonInheritanceConverter attributes with System.Text.Json JsonPolymorphicAttributes. To have the native support of inheritance (de)serialization and fallback to base types when payloads with (yet) unknown types are offered by newer versions of an API. See https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism for more information"
+    },    
+    "generateDisposableClients": {
+      "type": "boolean",
+      "description": "Set to `true` to generate disposable clients. Refit interfaces are generated as disposable clients."
+    },
     "dependencyInjectionSettings": {
       "type": "object",
       "properties": {

diff --git a/src/Refitter.SourceGenerator/README.md b/src/Refitter.SourceGenerator/README.md
@@ -66,7 +66,8 @@ The following is an example `.refitter` file
     "^/store/.*"
   ],
   "useDynamicQuerystringParameters": true, // Optional. Default=false
-  "usePolymorphicSerialization": false, // Optional. Default=false
+  "usePolymorphicSerialization": true, // Optional. Default=false
+  "generateDisposableClients": 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