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

[pravinkarthy]

Hi @RicoSuter I am using .Net Framework 4.7, NSwag.Generation.WebApi v 13.10.8 to have swagger in OWIN based WebApi. I want to have Exception type as camelcased and got the actual response as camelCase but Swagger documentation is still having PascalCase only for Exception object despite having the following setting with IgnoreSerializableInterface enabled.

appBuilder.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
            {
                settings.GeneratorSettings.DefaultUrlTemplate = "api/{controller}/{action}/{id}";
                settings.DocumentTitle = "Internal Service APIs"; // there is an open issue in the library for OWIN that does not set the title in generated UI. Works in .net core
                settings.GeneratorSettings.SerializerSettings = new JsonSerializerSettings
                {
                    ContractResolver = new CamelCasePropertyNamesContractResolver
                    {
                        IgnoreSerializableInterface = true
                    },
                    Converters = {new StringEnumConverter()}
                };
            });

Please advise if there is any other setting to be added. Thanks.