Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce C# Source Generator and the .refitter file format #86

Merged
merged 39 commits into from
Jul 27, 2023

Conversation

christianhelle
Copy link
Owner

The changes here introduce a C# Source Generator that uses Refitter for generating a REST API Client using the Refit library. Refitter can generate the Refit interface from OpenAPI specifications

The source generator is distributed as a NuGet package called Refitter.SourceGenerator and should be installed to the project that will contain the generated code

Usage

This source generator generates code based on any .refitter file included to the project as AdditionalFiles.

The generator can automatically detect all .refitter files inside the project that referenced the Refitter.SourceGenerator package and there is no need to include them manually as AdditionalFiles

File format

{
  "openApiPath": "/path/to/your/openAPI", // Required
  "namespace": "Org.System.Service.Api.GeneratedCode", // Optional. Default=GeneratedCode
  "naming": {
    "useOpenApiTitle": false, // Optional. Default=true
    "interfaceName": "MyApiClient" // Optional. Default=ApiClient
  },
  "generateContracts": true, // Optional. Default=true
  "generateXmlDocCodeComments": true, // Optional. Default=true
  "addAutoGeneratedHeader": true, // Optional. Default=true
  "returnIApiResponse": false, // Optional. Default=false
  "generateOperationHeaders": true, // Optional. Default=true
  "typeAccessibility": "Public", // Optional. Values=Public|Internal. Default=Public
  "useCancellationTokens": false, // Optional. Default=false
  "useIsoDateFormat": false, // Optional. Default=false
  "additionalNamespaces": [ // Optional
    "Namespace1",
    "Namespace2"
  ]
}
  • 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
  • namespace - the namespace used in the generated code. If not specified, this defaults to GeneratedCode
  • 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
  • generateContracts - a boolean indicating whether contracts should be generated. A use case for this is several API clients use the same contracts. Default is true
  • generateXmlDocCodeComments - a boolean indicating whether XML doc comments should be generated. Default is true
  • addAutoGeneratedHeader - a boolean indicating whether XML doc comments should be generated. Default is true
  • returnIApiResponse - a boolean indicating whether to return IApiResponse<T> objects. Default is false
  • generateOperationHeaders - a boolean indicating whether to use operation headers in the generated methods. Default is true
  • typeAccessibility - the generated type accessibility. Possible values are Public and Internal. Default is Public
  • useCancellationTokens - Use cancellation tokens in the generated methods. Default is false
  • 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
  • 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

Updated the RefitGeneratorSettings.cs file to include JSON property names for each setting. This change provides better serialization and deserialization, ensuring the settings correctly map to their respective JSON keys when using System.Text.Json.
Added a suppression attribute to bypass the analyzer warning for the GenerateNamespaceImports method in RefitInterfaceImports file. Additionally, formatted the GetImportedNamespaces method for better readability and added System.Diagnostics.CodeAnalysis namespace to the using directives. The analyzer was giving a false positive for a supposedly banned API which is not actually the case, hence the decision to suppress this specific warning.
Modified the suppression annotation of the 'MicrosoftCodeAnalysisCorrectness' warning in the RefitInterfaceImports.cs file to specify that the justification for using banned APIs is because the tool is cross platform. This change better communicates the intent and context of the suppression to fellow developers.
Removed the RootNamespace from the Directory.Build.props file as it was redundant. Also, pruned surplus properties from the Refitter.Tests.csproj file, which mainly consisted of unnecessary configurations that were inherited by default. Simplifying these files enhances readability and allows for easier project management.
This commit removes the package and publish steps from the build cycle in both the build and release workflows. This change is made because packaging and publishing do not need to be part of the build process. They have been taken out to make the process cleaner and more efficient.
@christianhelle christianhelle added the enhancement New feature, bug fix, or request label Jul 27, 2023
@christianhelle christianhelle merged commit 95fc1c3 into main Jul 27, 2023
@christianhelle christianhelle deleted the source-generator branch July 27, 2023 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature, bug fix, or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant