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.

Sign up for GitHub

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

[Apizr] Docs updated about Apizr integration #432

Merged
merged 2 commits into from
Jul 27, 2024
Merged

[Apizr] Docs updated about Apizr integration #432

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b132dec
[Apizr] Docs updated about Apizr integration
JeremyBP Jul 27, 2024
a224ffa
[Apizr] Updating docs with Apizr minimal version
JeremyBP Jul 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
297 changes: 294 additions & 3 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

8 changes: 7 additions & 1 deletion docs/docfx_project/articles/cli-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ EXAMPLES:
refitter ./openapi.json --no-deprecated-operations
refitter ./openapi.json --operation-name-template '{operationName}Async'
refitter ./openapi.json --optional-nullable-parameters
refitter ./openapi.json --use-apizr

ARGUMENTS:
[URL or input file] URL or file path to OpenAPI Specification file
Expand Down Expand Up @@ -82,7 +83,12 @@ OPTIONS:
- SingleClientFromOperationId
- SingleClientFromPathSegments
See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html for more information
--immutable-records Generate contracts as immutable records instead of classes
--immutable-records Generate contracts as immutable records instead of classes
--use-apizr Set to true to 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
```

To generate code from an OpenAPI specifications file, run the following:
Expand Down
411 changes: 411 additions & 0 deletions docs/docfx_project/articles/examples.md
View file
Open in desktop

Large diffs are not rendered by default.

70 changes: 70 additions & 0 deletions docs/docfx_project/articles/refitter-file-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,16 @@ The following is an example `.refitter` file
"maxRetryCount": 3, // Optional. Default=6
"firstBackoffRetryInSeconds": 0.5 // Optional. Default=1.0
},
"apizrSettings": { // Optional
"withRequestOptions": true, // Optional. Default=true
"withRegistrationHelper": true, // Optional. Default=false
"withCacheProvider": "InMemory", // Optional. Values=None|Akavache|MonkeyCache|InMemory|DistributedAsString|DistributedAsByteArray. Default=None
"withPriority": true, // Optional. Default=false
"withMediation": true, // Optional. Default=false
"withOptionalMediation": true, // Optional. Default=false
"withMappingProvider": "AutoMapper", // Optional. Values=None|AutoMapper|Mapster. Default=None
"withFileTransfer": true // Optional. Default=false
},
"codeGeneratorSettings": { // Optional. Default settings are the values set in this example
"requiredPropertiesMustBeDefined": true,
"generateDataAnnotations": true,
Expand Down Expand Up @@ -143,6 +153,15 @@ The following is an example `.refitter` file
- `transientErrorHandler`: Set this to configure transient error handling with a retry policy that uses a jittered backoff. See https://refitter.github.io/api/Refitter.Core.TransientErrorHandler.html
- `maxRetryCount` - This is the max retry count used in the Polly retry policy. Default is 6
- `firstBackoffRetryInSeconds` - This is the duration of the initial retry backoff. Default is 1 second
- `apizrSettings` - Setting this will format Refit interface to be managed by Apizr. See https://www.apizr.net for more information
- `withRequestOptions` - Tells if the Refit interface methods should have a final IApizrRequestOptions options parameter
- `withRegistrationHelper` - Tells if Refitter should generate Apizr registration helpers (extended with dependencyInjectionSettings set, otherwise static)
- `withCacheProvider` - Set the cache provider to be used
- `withPriority` - Tells if Apizr should handle request priority
- `withMediation` - Tells if Apizr should handle request mediation (extended only)
- `withOptionalMediation` - Tells if Apizr should handle optional request mediation (extended only)
- `withMappingProvider` - Set the mapping provider to be used
- `withFileTransfer` - Tells if Apizr should handle file transfer
- `codeGeneratorSettings` - Setting this allows customization of the NSwag generated types and contracts
- `requiredPropertiesMustBeDefined` - Default is true,
- `generateDataAnnotations` - Default is true,
Expand Down Expand Up @@ -357,6 +376,57 @@ The following is an example `.refitter` file
},
"description": "Settings for dependency injection."
},
"apizrSettings": {
"type": "object",
"properties": {
"withRequestOptions": {
"type": "boolean",
"description": "Tells if the Refit interface methods should have a final IApizrRequestOptions options parameter."
},
"withRegistrationHelper": {
"type": "boolean",
"description": "Tells if Refitter should generate Apizr registration helpers (extended with dependencyInjectionSettings set, otherwise static)."
},
"withCacheProvider": {
"type": "string",
"enum": [
"None",
"Akavache",
"MonkeyCache",
"InMemory",
"DistributedAsString",
"DistributedAsByteArray"
],
"description": "Set the cache provider to be used."
},
"withPriority": {
"type": "boolean",
"description": "Tells if Apizr should handle request priority."
},
"withMediation": {
"type": "boolean",
"description": "Tells if Apizr should handle request mediation (extended only)."
},
"withOptionalMediation": {
"type": "boolean",
"description": "Tells if Apizr should handle optional request mediation (extended only)."
},
"withMappingProvider": {
"type": "string",
"enum": [
"None",
"AutoMapper",
"Mapster"
],
"description": "Set the mapping provider to be used."
},
"withFileTransfer": {
"type": "boolean",
"description": "Tells if Apizr should handle file transfer."
}
},
"description": "Settings for Apizr."
},
"codeGeneratorSettings": {
"type": "object",
"properties": {
Expand Down
2 changes: 1 addition & 1 deletion docs/docfx_project/articles/source-generator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Source Generator

Refitter is available as a C# Source Generator that uses the [Refitter.Core](/api/Refitter.Core.html) 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
Refitter is available as a C# Source Generator that uses the [Refitter.Core](/api/Refitter.Core.html) 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. Refitter could format the generated Refit interface to be managed by [Apizr](https://www.apizr.net) and generate some registration helpers too.

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 (can be changed with `--outputFolder`). 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

Expand Down
Loading