"Added outputFilename option to configuration and updated documenta…

…tion" This commit adds an optional parameter `outputFilename` to the configuration options in the JSON files of `Refitter.SourceGenerator`, `../README` and `Refitter`. The `outputFilename` allows users to specify a name for the output file, with the default being `Output.cs` for the CLI tool. This change was necessary to provide users more flexibility in naming their output files. Additionally, the commit includes updates to the documentation files - `Refitter.SourceGenerator/README`, `../README`, `Refitter/README` and `../docs/docfx_project/articles/refitter-file-format.md` - to explain the new `outputFilename` option. It also adjusts the explanation on `operationNameTemplate` for clarity. Extra explanatory comments were added to `dependencyInjectionSettings` and a new block `codeGeneratorSettings` was included in the `Refitter/README.md` file to give users more control over the generated types and contracts.
christianhelle · Oct 26, 2023 · 50a21a4 · 50a21a4
1 parent ccdad77
commit 50a21a4
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -137,9 +137,10 @@ The following is an example `.refitter` file
   "useIsoDateFormat": false, // Optional. Default=false
   "multipleInterfaces": "ByEndpoint", // Optional. May be one of "ByEndpoint" or "ByTag"
   "generateDeprecatedOperations": false, // Optional. Default=true
-  "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName}
+  "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName} when multipleInterfaces != ByEndpoint
   "optionalParameters": false, // Optional. Default=false
   "outputFolder": "../CustomOutput" // Optional. Default=./Generated
+  "outputFilename": "RefitInterface.cs", // Optional. Default=Output.cs for CLI tool
   "additionalNamespaces": [ // Optional
     "Namespace1",
     "Namespace2"
@@ -215,6 +216,7 @@ The following is an example `.refitter` file
 - `useIsoDateFormat` - Set to `true` to explicitly format date query string parameters in ISO 8601 standard date format using delimiters (for example: 2023-06-15). Default is `false`
 - `multipleInterfaces` - Set to `ByEndpoint` to generate an interface for each endpoint, or `ByTag` to group Endpoints by their Tag (like SwaggerUI groups them).
 - `outputFolder` - a string describing a relative path to a desired output folder. Default is `./Generated`
+- `outputFilename` - Output filename. Default is `Output.cs` when used from the CLI tool, otherwise its the .refitter filename. So `Petstore.refitter` becomes `Petstore.cs`.
 - `additionalNamespaces` - A collection of additional namespaces to include in the generated file. A use case for this is when you want to reuse contracts from a different namespace than the generated code. Default is empty
 - `includeTags` - A collection of tags to use a filter for including endpoints that contain this tag.
 - `includePathMatches` - A collection of regular expressions used to filter paths.

diff --git a/docs/docfx_project/articles/refitter-file-format.md b/docs/docfx_project/articles/refitter-file-format.md
@@ -23,9 +23,10 @@ The following is an example `.refitter` file
   "useIsoDateFormat": false, // Optional. Default=false
   "multipleInterfaces": "ByEndpoint", // Optional. May be one of "ByEndpoint" or "ByTag"
   "generateDeprecatedOperations": false, // Optional. Default=true
-  "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName}
+  "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName} when multipleInterfaces != ByEndpoint
   "optionalParameters": false, // Optional. Default=false
   "outputFolder": "../CustomOutput" // Optional. Default=./Generated
+  "outputFilename": "RefitInterface.cs", // Optional. Default=Output.cs for CLI tool
   "additionalNamespaces": [ // Optional
     "Namespace1",
     "Namespace2"
@@ -39,7 +40,7 @@ The following is an example `.refitter` file
     "^/pet/.*",
     "^/store/.*"
   ],
-  "dependencyInjectionSettings": {
+  "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional
         "AuthorizationMessageHandler", 
@@ -86,8 +87,6 @@ The following is an example `.refitter` file
 }
 ```
 
-Here are some basic explanations of each property:
-
 - `openApiPath` - points to the OpenAPI Specifications file. This can be the path to a file stored on disk, relative to the `.refitter` file. This can also be a URL to a remote file that will be downloaded over HTTP/HTTPS
 - `naming.useOpenApiTitle` - a boolean indicating whether the OpenApi title should be used. Default is `true`
 - `naming.interfaceName` - the name of the generated interface. The generated code will automatically prefix this with `I` so if this set to `MyApiClient` then the generated interface is called `IMyApiClient`. Default is `ApiClient`
@@ -102,6 +101,7 @@ Here are some basic explanations of each property:
 - `useIsoDateFormat` - Set to `true` to explicitly format date query string parameters in ISO 8601 standard date format using delimiters (for example: 2023-06-15). Default is `false`
 - `multipleInterfaces` - Set to `ByEndpoint` to generate an interface for each endpoint, or `ByTag` to group Endpoints by their Tag (like SwaggerUI groups them).
 - `outputFolder` - a string describing a relative path to a desired output folder. Default is `./Generated`
+- `outputFilename` - Output filename. Default is `Output.cs` when used from the CLI tool, otherwise its the .refitter filename. So `Petstore.refitter` becomes `Petstore.cs`.
 - `additionalNamespaces` - A collection of additional namespaces to include in the generated file. A use case for this is when you want to reuse contracts from a different namespace than the generated code. Default is empty
 - `includeTags` - A collection of tags to use a filter for including endpoints that contain this tag.
 - `includePathMatches` - A collection of regular expressions used to filter paths.

diff --git a/src/Refitter.SourceGenerator/README.md b/src/Refitter.SourceGenerator/README.md
@@ -46,6 +46,7 @@ The following is an example `.refitter` file
   "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName} when multipleInterfaces != ByEndpoint
   "optionalParameters": false, // Optional. Default=false
   "outputFolder": "../CustomOutput" // Optional. Default=./Generated
+  "outputFilename": "RefitInterface.cs", // Optional. Default=Output.cs for CLI tool
   "additionalNamespaces": [ // Optional
     "Namespace1",
     "Namespace2"
@@ -59,7 +60,7 @@ The following is an example `.refitter` file
     "^/pet/.*",
     "^/store/.*"
   ],
-  "dependencyInjectionSettings": {
+  "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional
         "AuthorizationMessageHandler", 
@@ -122,6 +123,7 @@ The following is an example `.refitter` file
 - `useIsoDateFormat` - Set to `true` to explicitly format date query string parameters in ISO 8601 standard date format using delimiters (for example: 2023-06-15). Default is `false`
 - `multipleInterfaces` - Set to `ByEndpoint` to generate an interface for each endpoint, or `ByTag` to group Endpoints by their Tag (like SwaggerUI groups them).
 - `outputFolder` - a string describing a relative path to a desired output folder. Default is `./Generated`
+- `outputFilename` - Output filename. Default is `Output.cs` when used from the CLI tool, otherwise its the .refitter filename. So `Petstore.refitter` becomes `Petstore.cs`.
 - `additionalNamespaces` - A collection of additional namespaces to include in the generated file. A use case for this is when you want to reuse contracts from a different namespace than the generated code. Default is empty
 - `includeTags` - A collection of tags to use a filter for including endpoints that contain this tag.
 - `includePathMatches` - A collection of regular expressions used to filter paths.

diff --git a/src/Refitter/README.md b/src/Refitter/README.md
@@ -93,6 +93,7 @@ The following is an example `.refitter` file
   "operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName} when multipleInterfaces != ByEndpoint
   "optionalParameters": false, // Optional. Default=false
   "outputFolder": "../CustomOutput" // Optional. Default=./Generated
+  "outputFilename": "RefitInterface.cs", // Optional. Default=Output.cs for CLI tool
   "additionalNamespaces": [ // Optional
     "Namespace1",
     "Namespace2"
@@ -106,7 +107,7 @@ The following is an example `.refitter` file
     "^/pet/.*",
     "^/store/.*"
   ],
-  "dependencyInjectionSettings": {
+  "dependencyInjectionSettings": { // Optional
     "baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
     "httpMessageHandlers": [ // Optional
         "AuthorizationMessageHandler", 
@@ -115,6 +116,41 @@ The following is an example `.refitter` file
     "usePolly": true, // Optional. Set this to true, to configure Polly with a retry policy that uses a jittered backoff. Default=false
     "pollyMaxRetryCount": 3, // Optional. Default=6
     "firstBackoffRetryInSeconds": 0.5 // Optional. Default=1.0
+  },
+  "codeGeneratorSettings": { // Optional. Default settings are the values set in this example
+    "namespace": "GeneratedCode",
+    "requiredPropertiesMustBeDefined": true,
+    "generateDataAnnotations": true,
+    "anyType": "object",
+    "dateType": "System.DateTimeOffset",
+    "dateTimeType": "System.DateTimeOffset",
+    "timeType": "System.TimeSpan",
+    "timeSpanType": "System.TimeSpan",
+    "arrayType": "System.Collections.Generic.ICollection",
+    "dictionaryType": "System.Collections.Generic.IDictionary",
+    "arrayInstanceType": "System.Collections.ObjectModel.Collection",
+    "dictionaryInstanceType": "System.Collections.Generic.Dictionary",
+    "arrayBaseType": "System.Collections.ObjectModel.Collection",
+    "dictionaryBaseType": "System.Collections.Generic.Dictionary",
+    "propertySetterAccessModifier": "",
+    "generateImmutableArrayProperties": false,
+    "generateImmutableDictionaryProperties": false,
+    "handleReferences": false,
+    "jsonSerializerSettingsTransformationMethod": null,
+    "generateJsonMethods": false,
+    "enforceFlagEnums": false,
+    "inlineNamedDictionaries": false,
+    "inlineNamedTuples": true,
+    "inlineNamedArrays": false,
+    "generateOptionalPropertiesAsNullable": false,
+    "generateNullableReferenceTypes": false,
+    "generateNativeRecords": false,
+    "generateDefaultValues": true,
+    "inlineNamedAny": false,
+    "excludedTypeNames": [
+      "ExcludedTypeFoo",
+      "ExcludedTypeBar"
+    ]
   }
 }
 ```
@@ -134,11 +170,12 @@ The following is an example `.refitter` file
 - `useIsoDateFormat` - Set to `true` to explicitly format date query string parameters in ISO 8601 standard date format using delimiters (for example: 2023-06-15). Default is `false`
 - `multipleInterfaces` - Set to `ByEndpoint` to generate an interface for each endpoint, or `ByTag` to group Endpoints by their Tag (like SwaggerUI groups them).
 - `outputFolder` - a string describing a relative path to a desired output folder. Default is `./Generated`
+- `outputFilename` - Output filename. Default is `Output.cs` when used from the CLI tool, otherwise its the .refitter filename. So `Petstore.refitter` becomes `Petstore.cs`.
 - `additionalNamespaces` - A collection of additional namespaces to include in the generated file. A use case for this is when you want to reuse contracts from a different namespace than the generated code. Default is empty
 - `includeTags` - A collection of tags to use a filter for including endpoints that contain this tag.
 - `includePathMatches` - A collection of regular expressions used to filter paths.
 - `generateDeprecatedOperations` - a boolean indicating whether deprecated operations should be generated or skipped. Default is `true`
-- `operationNameTemplate` - Generate operation names using pattern. This must contain the string {operationName}. An example usage of this could be `{operationName}Async` to suffix all method names with Async. When using `"multipleIinterfaces": "ByEndpoint"`, This is name of the Execute() method in the interface
+- `operationNameTemplate` - Generate operation names using pattern. This must contain the string {operationName}. An example usage of this could be `{operationName}Async` to suffix all method names with Async
 - `optionalParameters` - Generate non-required parameters as nullable optional parameters
 - `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