Nswag: Obsolote warnings when upgrading from v11 to v12

[zorgoz]

Hello,

I had this piece of code:

app.UseSwaggerUi3(
   typeof(ControllerBase).GetAllAssignable()
   , (settings) =>
      {
         settings.GeneratorSettings.DefaultEnumHandling = NJsonSchema.EnumHandling.String;
     settings.GeneratorSettings.Title = "XYZ API v1";
     settings.GeneratorSettings.Version = "1.0";
     settings.GeneratorSettings.DefaultPropertyNameHandling = NJsonSchema.PropertyNameHandling.CamelCase;
      }
   , new NSwag.SwaggerGeneration.SwaggerJsonSchemaGenerator(new NJsonSchema.Generation.JsonSchemaGeneratorSettings())
);

Now I am getting _obsolote_ warning on settings.GeneratorSettings.DefaultEnumHandling and settings.GeneratorSettings.DefaultPropertyNameHandling. But the warning message makes no sense to me.

Severity Code Description Project File Line Suppression State
Warning CS0618 'JsonSchemaGeneratorSettings.DefaultEnumHandling' is obsolete: 'Use SerializerSettings directly instead. In NSwag.AspNetCore the property is set automatically.' ClientService

Please provide an example.

.Net Framework 4.7
NSwag.SwaggerGeneration.WebApi: 12.0.5.0

[RicoSuter]

It should look like this:

app.UseSwaggerUi3(typeof(ControllerBase).GetAllAssignable(), settings =>
    {
        settings.GeneratorSettings.Title = "XYZ API v1";
        settings.GeneratorSettings.Version = "1.0";

        settings.GeneratorSettings.SerializerSettings = new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver();
            Converters = { new StringEnumConverter() }
        }
    }, 
    new NSwag.SwaggerGeneration.SwaggerJsonSchemaGenerator(new NJsonSchema.Generation.JsonSchemaGeneratorSettings())
);

or just assign the settings from ASP.NET so that the configs match...

[Jrubzjeknf]

settings.GeneratorSettings is also marked as obsolete. I assume the settings.PostProcess should be used instead?

[RicoSuter]

NSwag.SwaggerGeneration.WebApi is deprecated for ASP.NET Core projects...

[zorgoz]

NSwag.SwaggerGeneration.WebApi is deprecated for ASP.NET Core projects...

But this is _not_ ASP.Net Core, it is a ASP.Net WebApi2 on top of Katana OWIN implementation

[RicoSuter]

GeneratorSettings is only deprecated in the NSwag.AspNetCore package:
https://github.com/RSuter/NSwag/blob/master/src/NSwag.AspNetCore/SwaggerSettings.cs#L40

If you’re using the owin package it should not be obsolete.

[NihatO]

NSwag.SwaggerGeneration.WebApi is deprecated for ASP.NET Core projects...

What is the actual alternative for NSwag 12 to handle this under Asp.net Core 2.2?
(e.g. for GeneratorSettings.DefaultEnumHandling = EnumHandling.String)

[RicoSuter]

NSwag.AspNetCore and this will use the mvc serializer settings, ie add a global StringEnumConverter in AddMvc().UseJson (or similar)

[CNBoland]

GeneratorSettings is only deprecated in the NSwag.AspNetCore package:
https://github.com/RSuter/NSwag/blob/master/src/NSwag.AspNetCore/SwaggerSettings.cs#L40

If you’re using the owin package it should not be obsolete.

I"m getting the build warning too after upgrading NSwag.AspNet.Owin from v11.20.1 to v12.0.9 in an application that targets .NET Framework 4.7.1. Perhaps a conditional compile symbol is misconfigured?

Here's the build error:

'JsonSchemaGeneratorSettings.DefaultPropertyNameHandling' is obsolete: 'Use SerializerSettings directly instead. In NSwag.AspNetCore the property is set automatically.'

[RicoSuter]

This is intended, just manually use the serializer settings, ie create a new settings instance and add eg a camel case contract resolver.. using these settings makes the stuff much more flexible and moves the logic out of nswag/njs

[NihatO]

NSwag.AspNetCore and this will use the mvc serializer settings, ie add a global StringEnumConverter in AddMvc().UseJson (or similar)

This way it works.
But with the previously possible setting
GeneratorSettings.DefaultEnumHandling = EnumHandling.String
we had the benefit, that the Web API gave back Enums as Integers (gain against Strings that the Enum-Names can be changed afterwards without breaking the API)
while the OpenAPI-Documentation showed the regarding Enums as Strings (much better documentation than just showing expressionless Integers)

Can i achieve this behaviour with NSwag 12?

[RicoSuter]

@NihatO even if you are using integer enums the names should be generated in x-enumNames - but i'm not sure if the UIs (e.g. swaggerui) handle that...

I think you can still override the serializer settings with an own one (i.e. different that the asp.net core settings) so that the spec is different than the serialized json