Use Swashbuckle instead of NSwag

[kjac]

Prerequisites

• I have added steps to test this contribution in the description below

Description

This PR replaces NSwag with Swashbuckle for OpenAPI schema generation.

Schema/model name generation

In order to get a more reasonable schema, a little bit of magic has also been introduced in ths PR, in order to shorten the generated schema/model names - i.e.:

• RelationItemViewModel becomes RelationItem
• PagedViewModelOfRelationItemViewModel becomes PagedRelationItem

This magic is performed by the SchemaIdGenerator. It is deliberately as static implementation, as it should never ever be replaced by means of DI. Refer to the implementation for details, it should be documented appropriately.

We may consider replacing the magic with explicit naming at some point. The magic path was chosen to achieve more reasonable schema as fast as possible, allowing the client to start using the schema sooner. There currently are some 100+ references to PagedViewModel<T>, most of which will have to be replaced if we go with explicit naming - and that's not even counting the "ViewModel" classes, which will also required explicit renaming.

Alternatively we could go the opt-in route where the auto generated schema names can be overridden by means of attribute decoration, but all this is subject to another discussion for another PR.

Included schemas

Endpoints returning CreatedResult and NotFoundObjectResult (basically any implementation of ObjectResult) cause the generated OpenAPI schema to contain the System.Type, System.Reflection.Assembly and all their referenced types (which is a LOT).

Upon closer inspection it turns out that NSwag deals with this by creating an "application/octet-stream" response, which is pretty useless to the client.

Swashbuckle on the other hand returns the correct type (i.e. CreatedResult), with the resulting overload of additional types being included in the schema.

This PR replaces a few of the CreatedResult and NotFoundObjectResult response definitions for this very reason, but not all of them - so System.Type etc. is still contained in the generated schema. We need to look into replacing CreatedResult ect. with custom models for all affected endpoints, in order to trim down the schema to that which is relevant for the Umbraco API. This task will be discussed elsewhere and handled separately from this PR, so for the time being we have to accept the additional schema types as-is.

Other points of interest

• TelemetryLevelViewModel has been renamed to TelemetryViewModel because the new, trimmed down model name (the output from SchemaIdGenerator) became TelemetryLevel which clashed with the referenced Umbraco.Cms.Core.Models.TelemetryLevel enum.
• Swashbuckle (and/or the bundled Swagger UI) does not seem to require a client secret for Authorization Code flows, so the ClientSecretManager (introduced with the new backoffice authentication solely for this specific purpose) has been removed. Yay!
• Swashbuckle refers to the default JSON serializer for supported MIME types. This means that "text/plain" and "text/json" start appearing in the OpenAPI schema as accepted MIME types for requests and responses, and we probably don't want to support that explicitly. Thus the MimeTypeDocumentFilter has been introduced to filter out all unwanted MIME types.

Testing this PR

1. Verify that the Swagger UI (/umbraco/swagger/index.html) still works.
2. Protect an endpoint (e.g. add [Authorize(Policy = $"New{AuthorizationPolicies.SectionAccessForMediaTree}")] to MediaTreeControllerBase) and verify that the Swagger authentication still works:
   
3. Verify that the schema does not contain any "ViewModel" postfixes.
4. Verify that paged list endpoints define a nice and tidy return model name - i.e. PagedLanguage instead of PagedViewModelOfLanguageViewModel:
   

[nikolajlauridsen]

Just had a peek through the code, and overall this looks good, I actually think the SchemaIdGenerator and MimeTypeDocumentFilter makes good sense even though it is slightly magic, but at least the code is reasonably easy to read and understand 🎉 But we can always discuss this a bit more with the entire team.

I have however noticed that our old nemesis: serializing enums has returned again leading to a mismatch between our schema and actual return value in modelsbuilder/dashboard for instance (it's present more places).

So in the swagger UI the example response is:

{
  "mode": 0,            <---- EnumAsInt
  "canGenerate": true,
  "outOfDateModels": true,
  "lastError": "string",
  "version": "string",
  "modelsNamespace": "string",
  "trackingOutOfDateModels": true
}

But the actual response is:

{
  "mode": "InMemoryAuto",    <--- EnumAsString
  "canGenerate": false,
  "outOfDateModels": false,
  "lastError": null,
  "version": "11.1.0--rc.preview.13+43ad93c",
  "modelsNamespace": "Umbraco.Cms.Web.Common.PublishedModels",
  "trackingOutOfDateModels": false
}

[nikolajlauridsen]

One thin that initially confused me a bit too was this code in the composer:

swaggerGenOptions.AddSecurityRequirement(new OpenApiSecurityRequirement  
{  
    {  
        new OpenApiSecurityScheme  
        {  
            Reference = new OpenApiReference  
            {  
                Id = "OAuth",  
                Type = ReferenceType.SecurityScheme  
            }  
        },  
        new List<string> { }  
    }  
});

It wasn't until I noticed that OpenApiSecurityRequirement inherits from a dictionary that it made sense, so that might be worth mentioning in a comment, mostly just because it looks quite weird otherwise

[kjac]

@nikolajlauridsen good grief, right you are! Good thing one of us is awake 😆

The enum serialization is fixed now - by means of yet another filter 🙈 the EnumSchemaFilter.

Here's what the Swagger output for the TelemetryLevel enum looks like with this filter applied:

The filter also supports the usage of EnumMemberAttribute decoration, meaning that this:

...will yield this Swagger output:

[kjac]

It wasn't until I noticed that OpenApiSecurityRequirement inherits from a dictionary that it made sense, so that might be worth mentioning in a comment, mostly just because it looks quite weird otherwise

Done 👍

[nikolajlauridsen]

I'm a happy hippo now, everything looks good to me 👍so let's get this merged, great work as always 😊