Table of Contents

NSwag

Warning

Deprecated

As Apizr.Tools.NSwag is now deprecated and will be removed in a future version, please consider using Refitter (v1.2+) instead which now can generate all the Apizr (v6+) boilerplate and more.

Apizr (v5.4-) comes with a now deprecated tool called Apizr.Tools.NSwag that offers to get all files generated by a couple of command lines. It relies on the well known NSwag CLI, letting define all we need in a json configuration file, and generating models, services and a registration helper class.

Installing

The first time you plan to use the tool, start by installing it:

Project Current Upcoming
Apizr.Tools.NSwag NuGet NuGet Pre Release 
> dotnet tool install --global Apizr.Tools.NSwag

Configuring

With Apizr.Tools.NSwag installed, navigate to the directory of your choice (the one where you want to generate files).

Create a configuration file

The first time you plan to use the tool for an api, you need to navigate to your target output folder and then run the new command:

> apizr new

From here, you'll get your apizr.json default configuration file into your current directory, looking like:

{
  "codeGenerators": {
    "openApiToApizrClient": {
      "registrationType": "Both",
      "withPriority": false,
      "withRetry": false,
      "withLogs": false,
      "withRequestOptions": false,
      "withCacheProvider": "None",
      "withMediation": false,
      "withOptionalMediation": false,
      "withMapping": "None",
      "className": "{controller}",
      "operationGenerationMode": "MultipleClientsFromOperationId",
      "additionalNamespaceUsages": [],
      "additionalContractNamespaceUsages": [],
      "generateOptionalParameters": false,
      "generateJsonMethods": false,
      "enforceFlagEnums": false,
      "parameterArrayType": "System.Collections.Generic.IEnumerable",
      "parameterDictionaryType": "System.Collections.Generic.IDictionary",
      "responseArrayType": "System.Collections.Generic.ICollection",
      "responseDictionaryType": "System.Collections.Generic.IDictionary",
      "wrapResponses": false,
      "wrapResponseMethods": [],
      "generateResponseClasses": true,
      "responseClass": "SwaggerResponse",
      "namespace": "MyNamespace",
      "requiredPropertiesMustBeDefined": true,
      "dateType": "System.DateTimeOffset",
      "jsonConverters": null,
      "anyType": "object",
      "dateTimeType": "System.DateTimeOffset",
      "timeType": "System.TimeSpan",
      "timeSpanType": "System.TimeSpan",
      "arrayType": "System.Collections.Generic.List",
      "arrayInstanceType": "System.Collections.Generic.List",
      "dictionaryType": "System.Collections.Generic.IDictionary",
      "dictionaryInstanceType": "System.Collections.Generic.Dictionary",
      "arrayBaseType": "System.Collections.ObjectModel.Collection",
      "dictionaryBaseType": "System.Collections.Generic.Dictionary",
      "classStyle": "Poco",
      "jsonLibrary": "NewtonsoftJson",
      "generateDefaultValues": true,
      "generateDataAnnotations": true,
      "excludedTypeNames": [],
      "excludedParameterNames": [],
      "handleReferences": false,
      "generateImmutableArrayProperties": false,
      "generateImmutableDictionaryProperties": false,
      "jsonSerializerSettingsTransformationMethod": null,
      "inlineNamedArrays": false,
      "inlineNamedDictionaries": false,
      "inlineNamedTuples": true,
      "inlineNamedAny": false,
      "generateDtoTypes": true,
      "generateOptionalPropertiesAsNullable": false,
      "generateNullableReferenceTypes": false,
      "templateDirectory": null,
      "typeNameGeneratorType": null,
      "propertyNameGeneratorType": null,
      "enumNameGeneratorType": null,
      "serviceHost": null,
      "serviceSchemes": null,
      "output": null,
      "newLineBehavior": "Auto"
    }
  },
  "runtime": "Net70",
  "defaultVariables": null,
  "documentGenerator": {
    "fromDocument": {
      "url": "http://redocly.github.io/redoc/openapi.yaml",
      "output": null,
      "newLineBehavior": "Auto"
    }
  }
}

Adjust configuration in file

Open your apizr.json file to edit the configuration.

Most of its settings are coming from NSwag configuration document definition as OpenApiToApizrClient comes from OpenApiToCSharpClient. It means that you can adjust everything you used to with classic NSwag generation.

Some of it must be adjusted:

  • into the openApiToApizrClient section:
    • namespace: the namespace used into generated files
    • output: a sub directory where to put generated files
  • into the fromDocument section:
    • url: the openapi json or yaml definition url
Warning

Minimal adjustments

Like for classic NSwag generation, you must at least complete these 3 settings. If not, nothing wil be generated.

That said, let's focus on Apizr dedicated settings into the openApiToApizrClient section:

  • registrationType (default: Both): generate a fluent registration helper class or not
    • None: do not generate
    • Static: generate with the static builder method
    • Extended: generate with the service collection extending method
    • Both: generate both methods (could be interesting to read but not relevant for production)
  • withPriority (default: false): include priority management into registration process
  • withRetry (default: false): add a Policy assembly attribute handling transient http error and a policy registry into registration process
  • withLogs (default: false): add a Log assembly attribute and a logger factory into static only registration process
  • withRequestOptions (default: false): add a RequestOptions parameter to your api methods so that you can adjust configuration at request time
  • withCacheProvider (default: None):
    • None: do not cache
    • Akavache: use Akavache
    • MonkeyCache: use MonkeyCache
    • InMemory: use Microsoft.Extensions.Caching.Memory (extended registration only)
    • Distributed: use any caching engine compatible with Microsoft.Extensions.Caching.Distributed.IDistributedCache (extended registration only)
    • Custom: use your own ICachingHandler implementation
  • withMediation (default: false): add mediation into extended registration process (extended registration only)
  • withOptionalMediation (default: false): add optional mediation into extended registration process (extended registration only)
  • withMapping (default: None):
    • None: do not map data
    • AutoMapper: use AutoMapper
    • Mapster: use Mapster

Generating

Once configuration file has been adjusted to your needs, execute the run command from the same directory where your apizr.json stands:

> apizr run
Note

Optional arguments

You can provide optional arguments:

  • Input argument if you'd like to set a specific json configuration file path to run with. Ignore it as long as your directory contains only one of it.
  • Variables argument if you need to set some dynamic values. Ignore it if you don't know what you're doing or read the NSwag doc about it.

You should now get all your generated files right in place in your configured output folder.

While you'll be including these files in your project, don't forget to install Nuget package dependencies as listed into the generated comments.

Edit this page