Add Support for Swagger

[commonsensesoftware]

Add basic support for Swagger. The Swagger functionality should be supported for all of the platforms:

• ASP.NET Web API
• ASP.NET Web API with OData v4.0
• ASP.NET Core

[CumpsD]

If it helps, when I currently use this and Swagger, Swagger outputs these things:

[scoleman81]

I am not sure what you are after here but in the last day or so I have been adding swagger and api versioning to a new core api site I am working on. I wanted my version and a functional area split out in my swagger docs. I am using swashbuckle to implement swagger (Swashbuckle.AspNetCore). The way I implemented this was all on the swagger generation side not in versioning. I decided to generate separate documents for each API version (and namespace in my case) I was going to have. Then it is just a mater of selecting the document for the api I want to see. You can also insert a default query or header parameter and it will just work. I have attached some of my code if it helps.

In the end I get a list of swagger documents for my api that is split by a functional area (portion of the namespace) and api version ie

DoSomeWorkGroup1 - v1.0
DoSomeWorkGroup1 - v2.0
DoSomeWorkGroup2 - v2.0
etc

Generate a list of Namespaces and Versions for Swagger:

public static class SwaggerDocuments
{
    public static List<SwaggerDocument> GetSwaggerDocumentList()
    {
        var APIGroups = new List<SwaggerDocument>();
        Assembly asm = Assembly.GetExecutingAssembly();
        var controllers = asm.GetTypes()
            .Where(type => typeof(Controller).IsAssignableFrom(type))
            .SelectMany(type => type.GetMethods())
            .Where(method => method.IsPublic && !method.IsDefined(typeof(NonActionAttribute)));

        foreach (var controller in controllers)
        {
            Type t = controller.GetType();
            var Namespace = controller.DeclaringType.Namespace;

            var attributes = controller.DeclaringType.CustomAttributes;

            foreach (var item in attributes)
            {
                if (item.AttributeType == typeof(ApiVersionAttribute))
                {
                    foreach (var version in item.ConstructorArguments)
                    {
                        APIGroups.Add(new SwaggerDocument() { Namespace = Namespace.Replace("<Namespace Prefix I want Removed>.", "").Split('.').First(), Version = version.Value.ToString() });
                    }
                }
            }
        }

        return APIGroups.GroupBy(x => new { x.Namespace, x.Version }).Select(x => new SwaggerDocument { Namespace = x.Key.Namespace, Version = x.Key.Version }).ToList();
    }

    public class SwaggerDocument
    {
        public string Namespace { get; set; }
        public string Version { get; set; }
    }
}

Swagger generation in ConfigureServices of Startup Class

services.AddMvc(c =>
    c.Conventions.Add(new ApiExplorerGroupPerVersionConvention())
);
services.AddSwaggerGen(c =>
{
    var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "BG.Connect.API.xml");
    c.IncludeXmlComments(filePath);

    foreach (var item in Apilist)
    {
        c.SwaggerDoc($"{item.Namespace}{item.Version}", new Info { Title = $"{item.Namespace} API", Version = item.Version });
    }
    c.OperationFilter<AddRequiredHeaderParameter>();
    c.DocInclusionPredicate((docName, apiDesc) =>
    {
        var restrictedVersion = apiDesc.ActionAttributes()
            .OfType<MapToApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);

        var versions = apiDesc.ControllerAttributes()
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);
        if (restrictedVersion.Count() > 0)
        {
            return restrictedVersion.Any(v => $"{apiDesc.GroupName}{v.ToString()}" == docName);
        }
        else
        {
            return versions.Any(v => $"{apiDesc.GroupName}{v.ToString()}" == docName);
        }
    });
});

Swagger UI Settings in Configure of Startup Class

app.UseSwaggerUi(c =>
{
     foreach (var item in Apilist)
    {
        c.SwaggerEndpoint($"/swagger/{item.Namespace}{item.Version}/swagger.json", $"{item.Namespace} API - v{item.Version}");
    }
});

Helper Class Used to Get the Portion of the namespace I want to split the documents by.

public class ApiExplorerGroupPerVersionConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        var controllerNamespace = controller.ControllerType.Namespace; // e.g. "Controllers.V1"
        var apiVersion = controllerNamespace.Replace("<Namespace Prefix I want Removed>", "").Split('.').First();

        controller.ApiExplorer.GroupName = apiVersion;
    }
}

Helper Function to add the needed query or header parameters to all Item:

public class AddRequiredHeaderParameter : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            string Version = "";
            var controllerActionDescriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;
            if (controllerActionDescriptor != null)
            {
                var controllerAttributes = controllerActionDescriptor.ControllerTypeInfo.CustomAttributes;

                foreach (var item in controllerAttributes)
                {
                    if (item.AttributeType == typeof(ApiVersionAttribute))
                    {
                        foreach (var version in item.ConstructorArguments)
                        {
                            Version = version.Value.ToString();
                        }
                    }
                }
                
                var methodAttributes = controllerActionDescriptor.MethodInfo.CustomAttributes;

                foreach (var item in methodAttributes)
                {
                    if (item.AttributeType == typeof(MapToApiVersionAttribute))
                    {
                        foreach (var version in item.ConstructorArguments)
                        {
                            Version = version.Value.ToString();
                        }
                    }
                }
            }

            var header = new NonBodyParameter
            {
                Name = "api-version",
                In = "query",
                Required = true,
                Type = "string",
                Default = Version

            };

            if (operation.Parameters == null)
            {
                operation.Parameters = new List<IParameter>();
            }

            operation.Parameters.Add(header);
        }
    }

Hope this helps.

[xperiandri]

Do you mean like releasing a package related to API Versioning with a solution from here packaged into a single library with easy setup?

[commonsensesoftware]

Exactly. An interesting challenge is how to aggregate the controller versions for documentation. In the versioning libraries this happens by letting the routing infrastructure find all candidates for a route and then aggregating from there. In addition, the client knows the route their looking for. For documentation, all of the routes need to be collated and then aggregated. I know this is possible, but the implementation has yet to be hashed out.

Another aspect is making sure that the documentation is built using the right abstractions. A lot of the early variants that I'm seeing people build are based on attributes. This not actually what the API versioning libraries use. The libraries only care about IApiVersionProvider and IApiVersionNeutral. One of the ways these interfaces are realized just happen to be attributes.

It's important for the right abstractions are used so that the solution is generic and can be used for various API versioning scenarios. Regardless, there has been some great progress in a number of attempts to create a library and I'll certainly be reviewing the implementations I know about for input to the out-of-the-box solution.

Now that I've nearly burned down all of the other issues, I should have some time (soon) to dedicate to this feature. Thanks for your patience.

[xperiandri]

So what help do you need?
Do you want a pull request that adds a separate project with SwashBuckle filters that I referenced?
RemoveVersionParameters : IOperationFilter
abstract SetVersionInPaths : IDocumentFilter that requires to implement version replacement logic.

[commonsensesoftware]

Someone looking to help ... yeah! Coincidentally, I've finally burned down just about every other outstanding issue, so I can now give this topic the full attention it deserves. Admittedly, I haven't spent a bunch of hands-on time with Swagger and Swashbuckle, so I'll be looking for feedback there for sure. I'll be catching myself up as quickly as possible. Here's the 10,000ft overview:

Objective

Provide an aggregated API version meta-model that groups all services (e.g. controllers) by route and their associated API versions. This is the part that is difficult and provides the value proposition to service authors. The result should be something analogous to, if not an implementation of, an API Explorer that is API version aware. This will provide all the heavy lifting for service authors and can potentially live directly within the API versioning libraries. I'm up in the air as to whether a separate library should be required for these capabilities. Opinions are welcome.

Requirements

• Controllers must be collated by route (this is probably the most challenging part)
• API version information must be based on IApiVersionProvider and IApiVersionNeutral (not solely attributes)
  • Once you can get down to the controller or action descriptors, this information can be collected using the built-in GetApiVersionModel extension methods
• API version information should be aggregated into a single ApiVersionModel per route
  • Built-in extension methods exist to aggregate ApiVersionModel instances
• Implement IApiExplorer for ASP.NET Web API, if possible/feasible
• Implement IApiDescriptionProvider for ASP.NET Core, if possible/feasible

[jlopresti]

Hi guyz !

Just play with versioning and swagger few days ago and here is what I found :
We have to declare :

• 1 Swagger Document per version : Technically we have to configure SwaggerGen Service
• We all version available for a given action : Use Swagger method DocInclusionPredicate inside SwaggerGen config service
• Enable SwaggerUI middleware and add Endpoint for each version

For DocInclusionPredicate we already have all the api to configure this method because ApiVersionModel has been built by ApiVersionConvention :

 c.DocInclusionPredicate((docName, apiDesc) =>
                {
                    var model = apiDesc.ActionDescriptor.GetProperty<ApiVersionModel>();
                    var version = docName;
                    if (model.IsApiVersionNeutral)
                    {
                        return true;
                    }
                    else if (model.DeclaredApiVersions.Any())
                    {
                        return model.DeclaredApiVersions.Any(_ => _.ToString() == version);
                    }                    
                    else if (model.ImplementedApiVersions.Any())
                    {
                        return model.ImplementedApiVersions.Any(_ => _.ToString() == version);
                    }

                    return false;
                });

For other points, we can't use that because ApplicationModel hasn't been executed yet but to build SwaggerDoc and SwaggerEndpoint we just have to know all version available into our application not necessarily which action is available in a specific version

Example of code to configure swagger doc and endpoint :

            app.UseSwaggerUI(c =>
            {
                foreach (var version in versions)
                {
                    c.SwaggerEndpoint($"/swagger/v{version}/swagger.json", $"V{version} Docs");
                }
            }); 

// Register the Swagger generator, defining one or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                foreach (var version in versions)
                {
                    c.SwaggerDoc($"v{version}", new Info { Title = $"Sample service v{version}", Version = $"v{version}" });
                }

                c.DocInclusionPredicate((docName, apiDesc) =>
                {
                      //implem is above
                       ...
                });
            });

[xperiandri]

Or like this

options.DocInclusionPredicate((docName, apiDesc) =>
{
    var model = apiDesc.ActionDescriptor.GetProperty<ApiVersionModel>();
    switch (model)
    {
        case ApiVersionModel _ when model.IsApiVersionNeutral: return true;
        case ApiVersionModel _ when model.DeclaredApiVersions.Any():
            return model.DeclaredApiVersions
                        .Any(apiVersion => apiVersion.ToString() == docName);
        case ApiVersionModel _ when model.ImplementedApiVersions.Any():
            return model.ImplementedApiVersions
                        .Any(apiVersion => apiVersion.ToString() == docName);
        default: return false;
    }
});