Add Support for API Explorer

[commonsensesoftware]

Overview

Add out-of-the-box support for the API Explorer. The implementation should enable enumerating controllers and their associated actions, which are grouped by API version .

Requirements

• Enable enumeration of API-versioned controllers and actions
• Simplify documenting API-versioned services using Swagger
• Simplify documenting API-versioned services using Swashbuckle
• [Optional] Extend support to ASP.NET Web API Help Pages

Tasks

• Implement IApiExplorer for ASP.NET Web API
• Implement IApiExplorer for ASP.NET Core
• Implement IApiExplorer for ASP.NET Web API with OData

[nomttr]

I found article which turned out to be very helpful in case of versioning and Web API Help Page. It isn't perfect but in 95% of cases it works perfectly! All of step are explained in the article. I changed implementation of GetFriendlyID method to takes api versioning into the account. In my case i'm using url versioning so RelativePath always conatins {version} string but you should consider another versioning strategies.

ApiDescriptionExtensions

public static string GetFriendlyId(this ApiDescription description)
        {
            if (description.RelativePath.Contains("{version}"))
            {
                var controllerApiVersion = description.ActionDescriptor.ControllerDescriptor.GetImplementedApiVersions().FirstOrDefault(); //consider that each controller can implement only one ApiVersion
                if (controllerApiVersion != null)
                {
                    StringBuilder apiVersionValue = new StringBuilder();

                    if (controllerApiVersion.MinorVersion != null && controllerApiVersion.MinorVersion != 0)
                    {
                        apiVersionValue.AppendFormat("{0}.{1}", controllerApiVersion.MajorVersion, controllerApiVersion.MinorVersion);
                    }
                    else
                    {
                        apiVersionValue.AppendFormat(controllerApiVersion.MajorVersion.ToString());
                    }

                    description.RelativePath = description.RelativePath.Replace("{version}", apiVersionValue.ToString());
                }
            }
                     //omitted
      }

Issue I found in this solution affects identical routes but different HttpMethods. In this case it treats them as matching routes and because of this it creates more ApiDescriptions than actually exist. Workaround for this issue is to distinct Model in the ApiGroup.cshtml but I think there is better solution for this case.

ApiGroup.cshtml

@model IGrouping<HttpControllerDescriptor, ApiDescription>

       //omitted

        @{
            IEnumerable<ApiDescription> apiGroup = Model.ToList().DistinctBy(d => d.GetFriendlyId());

            foreach (var apiDescription in apiGroup.OrderByDescending(r => r.RelativePath))
            {
                <tr>
                    <td class="api-name"><a href="@Url.Action("Api", "Help", new {apiId = apiDescription.GetFriendlyId()})">@apiDescription.HttpMethod.Method @apiDescription.RelativePath</a></td>
                    <td class="api-documentation">
                        @if (apiDescription.Documentation != null || !string.IsNullOrWhiteSpace(apiDescription.Documentation))
                        {
                            <p>@apiDescription.Documentation</p>
                        }
                        else
                        {
                            <p>No documentation available.</p>
                        }
                    </td>
                </tr>
         }

I think you should consider to add this code to your solution. Probably you have to suit it to be more universal but at least it's a great starting point. Hope this gonna be helpful for you and looking forward for changes!

[commonsensesoftware]

Nice. This is will be useful. I've started taking a crack at creating an IApiExplorer that adds support for versioning. The built-in implementation uses a lot of internal types and methods, which makes the port more difficult. This is a great link. It might negate the need to folk the original code and rather adapt over it. I'm hoping to have a beta version of the functionality out during the holidays. Thanks for sharing.

[commonsensesoftware]

The first iteration of packages are available. I'm leaving a little burn-in time with a beta release for issues and/or feedback before the official release. I'll be updating the wiki soon.

• Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
• Microsoft.AspNet.WebApi.Versioning.ApiExplorer
• Microsoft.AspNet.OData.Versioning.ApiExplorer

[xperiandri]

@commonsensesoftware, how to remove letter v from group name?

[commonsensesoftware]

Good question. I guess I haven't really documented those scenarios yet. This is handled by the IApiVersionGroupNameFormatter service. The default behavior is implemented by the DefaultApiVersionGroupNameFormatter.

This class is sealed for now because there's nothing to extend or override in the base implementation thus far. The single method defined by the interface is responsible for formatting a given ApiVersion as a group name. To change it, just add your own implementation and then replace that service in the services collection as a singleton.

services.TryAddSingleton<IApiVersionGroupNameFormatter, MyApiVersionGroupNameFormatter>();

The default implementation uses a v because that seemed to be what most people use in their Swagger documentation. If you have alternate ideas or suggestions, please share. I hope that helps. Let me know if you have any more questions.