From fa75c2eab59d3de18918e894dd4e4945d94a1646 Mon Sep 17 00:00:00 2001 From: Christian Helle Date: Tue, 24 Oct 2023 11:03:17 +0200 Subject: [PATCH] "Added `outputFilename` option to configuration and updated documentation" 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. --- README.md | 4 +- .../articles/refitter-file-format.md | 8 ++-- src/Refitter.SourceGenerator/README.md | 4 +- src/Refitter/README.md | 41 ++++++++++++++++++- 4 files changed, 49 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 56802d0e..b726460d 100644 --- a/README.md +++ b/README.md @@ -136,9 +136,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" @@ -214,6 +215,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 index 56da178d..c6874e7a 100644 --- 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 index 6e3f771d..0f57d376 100644 --- 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 index 2b56c642..c5e9f269 100644 --- 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