From 35954ce5e333d8136f127edf10f36302bdf5bda9 Mon Sep 17 00:00:00 2001 From: Christian Helle Date: Sat, 12 Aug 2023 00:29:58 +0200 Subject: [PATCH 1/4] Include source generator in release build --- .github/workflows/release-template.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release-template.yml b/.github/workflows/release-template.yml index 2541ec9c..7ed83b53 100644 --- a/.github/workflows/release-template.yml +++ b/.github/workflows/release-template.yml @@ -27,7 +27,7 @@ jobs: working-directory: src/Refitter.Core/ shell: pwsh - name: Build - run: dotnet build -c Release src/Refitter/Refitter.csproj -p:UseSourceLink=true -p:PackageVersion="${{ inputs.version }}" + run: dotnet build -c Release src/Refitter.sln -p:UseSourceLink=true -p:PackageVersion="${{ inputs.version }}" - name: Move packages shell: pwsh run: Get-ChildItem -Filter *.nupkg -Recurse | ForEach-Object { Move-Item -Path $_ -Destination . } From 1d158ca0f76923516877be360a60d1ba0177f129 Mon Sep 17 00:00:00 2001 From: Christian Helle Date: Sat, 12 Aug 2023 00:44:07 +0200 Subject: [PATCH 2/4] Restore source generator docs in README --- README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 92034446..87f9ac90 100644 --- a/README.md +++ b/README.md @@ -71,15 +71,87 @@ $ refitter [path to OpenAPI spec file] --namespace "[Your.Namespace.Of.Choice.Ge This will generate a file called `Output.cs` which contains the Refit interface and contract classes generated using [NSwag](https://github.com/RicoSuter/NSwag) +## Source Generator -## Using the generated code +Refitter is available as a C# Source Generator that uses the [Refitter.Core](https://github.com/christianhelle/refitter.core) library for generating a REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface from OpenAPI specifications + +### Installation + +The source generator is distributed as a NuGet package and should be installed to the project that will contain the generated code + +```shell +dotnet add package Refitter.SourceGenerator +``` + +### 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` + +### .Refitter File format + +The following is an example `.refitter` file + +```js +{ + "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 + "multipleInterfaces": "ByEndpoint", // Optional. May be one of "ByEndpoint" or "ByTag" + "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` 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` +- `multipleInterfaces` - Set to `ByEndpoint` to generate an interface for each endpoint, or `ByTag` to group Endpoints by their Tag (like SwaggerUI groups them). +- `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 + + +# Using the generated code Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) using the default settings +**CLI Tool** + ```bash $ refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" ``` +**Source Generator ***.refitter*** file** + +```json +{ + "openApiPath": "./openapi.json", + "namespace": "Your.Namespace.Of.Choice.GeneratedCode" +} +``` + **Output** ```cs @@ -192,10 +264,22 @@ namespace Your.Namespace.Of.Choice.GeneratedCode Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) configured to wrap the return type in `IApiResponse` +**CLI Tool** + ```bash $ refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --use-api-response ``` +**Source Generator ***.refitter*** file** + +```json +{ + "openApiPath": "./openapi.json", + "namespace": "Your.Namespace.Of.Choice.GeneratedCode", + "returnIApiResponse": true +} +``` + **Output** ```cs @@ -308,10 +392,22 @@ namespace Your.Namespace.Of.Choice.GeneratedCode.WithApiResponse Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) configured to generate an interface for each endpoint +**CLI Tool** + ```bash $ refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --multiple-interfaces ByEndpoint ``` +**Source Generator ***.refitter*** file** + +```json +{ + "openApiPath": "./openapi.json", + "namespace": "Your.Namespace.Of.Choice.GeneratedCode", + "multipleInterfaces": "ByEndpoint" +} +``` + **Output** ```cs From bf5cd5879dbaa314cbca1d8501f84475fb216d50 Mon Sep 17 00:00:00 2001 From: Christian Helle Date: Sat, 12 Aug 2023 09:59:04 +0200 Subject: [PATCH 3/4] Restore distribution info in README --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 87f9ac90..394bd5c7 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,11 @@ # Refitter Refitter is a tool for generating a C# REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface and contracts from OpenAPI specifications. The [.NET CLI Tool](#cli-tool) distributed via [nuget.org](http://www.nuget.org/packages/refitter) that outputs a single C# file on disk -## Getting Started +Refitter comes in 2 forms: +- A [.NET CLI Tool](#cli-tool) distributed via [nuget.org](http://www.nuget.org/packages/refitter) that outputs a single C# file on disk +- A [C# Source Generator](#source-generator) via the [Refitter.SourceGenerator](http://www.nuget.org/packages/refitter.sourcegenerator) package that generates code on compile time based on a [.refitter](#.refitter-file-format) within the project directory + +## CLI Tool ### Installation: From 063fc065fd055ca6d63d82a096c32b5f4a9c0671 Mon Sep 17 00:00:00 2001 From: Christian Helle Date: Sat, 12 Aug 2023 10:05:55 +0200 Subject: [PATCH 4/4] Update README Add explanations as to how the Refitter source generator works --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 394bd5c7..901fe58e 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ # Refitter -Refitter is a tool for generating a C# REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface and contracts from OpenAPI specifications. The [.NET CLI Tool](#cli-tool) distributed via [nuget.org](http://www.nuget.org/packages/refitter) that outputs a single C# file on disk +Refitter is a tool for generating a C# REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface and contracts from OpenAPI specifications. Refitter comes in 2 forms: - A [.NET CLI Tool](#cli-tool) distributed via [nuget.org](http://www.nuget.org/packages/refitter) that outputs a single C# file on disk -- A [C# Source Generator](#source-generator) via the [Refitter.SourceGenerator](http://www.nuget.org/packages/refitter.sourcegenerator) package that generates code on compile time based on a [.refitter](#.refitter-file-format) within the project directory +- A [C# Source Generator](#source-generator) via the [Refitter.SourceGenerator](http://www.nuget.org/packages/refitter.sourcegenerator) package that generates code on compile time based on a [.refitter](#.refitter-file-format) within the project directory. ## CLI Tool @@ -79,6 +79,10 @@ This will generate a file called `Output.cs` which contains the Refit interface Refitter is available as a C# Source Generator that uses the [Refitter.Core](https://github.com/christianhelle/refitter.core) library for generating a REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface from OpenAPI specifications +The Refitter source generator is a bit untraditional in a sense that it creates a folder called `Generated` in the same location as the `.refitter` file and generates files to disk under the `Generated` folder. The source generator output should be included in the project and committed to source control. This is done because there is no other way to trigger the Refit source generator to pickup the Refitter generated code + +***(Translation: I couldn't for the life of me figure how to get that to work, sorry)*** + ### Installation The source generator is distributed as a NuGet package and should be installed to the project that will contain the generated code