Add a Custom Description In Swagger For Each API Version

[kevinwinmill]

I'm looking for a way to add a custom description or comment to each API version which could then be added to the top of the swagger documentation in OpenApiInfo.Description.

I've been trying to find if that use case is possible using the existing package.  Adding a status to the version almost meets my needs in order to convey a message to consumers of the API, but I want to convey a message through the description instead and avoid the status being included in the API endpoint URLs, as this would require subsequent code changes by consumers when the status is finalized.  My preference would be to have a property added to ApiVersionDescription that could be used to add this custom description, which I believes resolves this in a simple manner that is in line with the rest of the package's logic.  The custom description would be added to the OpenApiInfo.Description similar to how the SunsetPolicy/IsDeprecated properties allow us to update the Description. My sample code snippet below follows the CreateInfoForApiVersion method here: https://github.com/dotnet/aspnet-api-versioning/blob/main/examples/AspNetCore/WebApi/OpenApiExample/ConfigureSwaggerOptions.cs. At the end I've added use of a CustomDescription property that doesn't exist right now, but is what I'm looking for.  The specific name of the property is less important, of course, than the functionality - it could be called 'comment'.

private OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
{
	var info = new OpenApiInfo();
	if (!string.IsNullOrEmpty(Configuration.OpenApi.Title))
	{
		info.Title = Configuration.OpenApi.Title;
	}

	info.Version = description.ApiVersion.ToString();

	var text = new StringBuilder("");
	if (description.IsDeprecated)
	{
		text.Append("This API version has been deprecated.");
	}

	if (description.SunsetPolicy is SunsetPolicy policy)
	{
		if (policy.Date is DateTimeOffset when)
		{
			text.Append(" The API will be sunset on ")
				.Append(when.Date.ToShortDateString())
				.Append('.');
		}

		if (policy.HasLinks)
		{
			text.AppendLine();

			for (var i = 0; i < policy.Links.Count; i++)
			{
				var link = policy.Links[i];

				if (link.Type == "text/html")
				{
					text.AppendLine();

					if (link.Title.HasValue)
					{
						text.Append(link.Title.Value).Append(": ");
					}

					text.Append(link.LinkTarget.OriginalString);
				}
			}
		}
	}

	if (description.CustomDescription)
	{
		text.AppendLine();

		text.Append($" {description.CustomDescription}.");
	}

	info.Description = text.ToString();

	return info;
}

I found a discussion that is very similar to what I'm looking for: #899.

In my situation I loop through provider.ApiVersionDescriptions and call CreateInfoForApiVersion from an in-house nuget package that is used by all of our APIs.  I'm hoping to leave this generic code in place, but be able to create in AddAPIVersioning a per-version property I can consume when I process each iteration of this loop.  A string would work well, a dictionary<string,string> would also work and may be more future-proof should we need more than one property.

[DM1145]

I'm running into a very similar issue.

Is there a way in the current package version to get descriptive text included at the top of the API page in swagger next to my api-level deprecated / sunset content by way of the current ApiVersionDescription object? I'd think there should be, if only to enhance the swagger page with explanatory text on how to use (and how not to use) the APIs we're writing.

[commonsensesoftware]

Interesting request. I'm trying to envision how this would be configured. API Versioning very intentionally limits its extension points to the API Explorer surface area and only bridges gaps that are not otherwise supportable; for example, deprecation and sunset policies. The extensions can be (and most often are) used for OpenAPI, but that is not their objective. There are scenarios outside of documentation (ex: test automation) that they are useful for. The goal has always been to derive as much from convention as possible. A description for an API cannot really be defined. This is already an issue without API Versioning, but is further conflated by a combination of API + API version.

Honestly, this type of issue feels more in the realm of OpenAPI/Swagger than API Versioning. I'm not saying "No", but I need to understand what this would look like. Swashbuckle already provides a couple of ways to provide detailed API-level documentation. Why wouldn't you just use that approach? If you need more than can be conveyed in the description, you'll need custom code as you already have. If the built-in description capabilities don't work, this is where you could add that hook today.

There's only two limitations in the current way Swashbuckle would pick up the description from today. First, if you interleave API versions on a single type or endpoint and want different descriptions, that's not supported. The easiest solution there is to simply split the APIs out into different controllers or endpoint mappings. The other issue would be if you want more control over the order and arrangement of the text. The simplest solution there seems to be back at creating custom code to build the description the way you want. It appears that even if you had a new description property, you'd still need user-defined code to stitch the pieces together. Since it would only be used for OpenAPI descriptions (best as I can tell), the extension points in the OpenAPI generator such as Swashbuckle or NSwag are better suited to address it.

[kevinwinmill]

I appreciate the response and suggestion.

That makes sense to limit API Versioning extensions to deprecation and sunset policies. In trying to add a custom description unique to each version, it felt like the most simple and clean way would be to include it with those two properties. I agree that it's more in the realm of OpenAPI though.

@Mhirji, thanks for your reply as well. I'll add the solution I implemented below in case it helps anyone who comes to this thread.

I have a custom OpenApiConfiguration class to which I've added this property:
public Dictionary<string,string> VersionDescriptions { get; set; }

In the constructor, I set these values from my appsetting.json config file

VersionDescriptions = new Dictionary<string,string>();
var versionDescriptions = configuration.GetSection("APIVersionDescriptions").GetChildren();
foreach (var versionDescription in versionDescriptions)
{
    VersionDescriptions.Add(versionDescription.Key, versionDescription.Value);
};

Here is the section added in my appsettings.json

"APIVersionDescriptions": {
    "v1": "This version is currently under development.",
    "v0": "This version is being replaced by v1."
  }

Finally, within my CreateInfoForApiVersion method that returns the OpenApiInfo object, I have this block of code:

if (Configuration.OpenApi.VersionDescriptions.ContainsKey(description.GroupName))
{
    if (text.Length > 0)
    {
        text.AppendLine();
        text.AppendLine();
    }
    
    text.Append($"{Configuration.OpenApi.VersionDescriptions[description.GroupName]}");
}

[Mhirji]

@kwinmill7 , not sure if this is relevant, but in my case I add the change log for each version to the OpenAPI document's description. To do this, each version has a class which returns the markdown string for the entire description property.

private static OpenApiInfo CreateInfoForApiVersion( ApiVersionDescription description )
    {
        var text = Docs.DocumentationLoader.GetDoc( description.ApiVersion );

        var info = new OpenApiInfo()
        {
            Title = $"Some title",
            Version = description.ApiVersion.ToString(),
            Description = text, 
            Contact = new OpenApiContact() { Name = "Name", Email = "Email" },
        };

        if ( description.IsDeprecated )
        {
            info.Description += " This API version has been deprecated.";
        }

        return info;
    }

public static string GetDoc( ApiVersion version )
    {
        switch ( version.MajorVersion )
        {
            case 3:
                switch ( version.MinorVersion )
                {
                    case 0:
                        return Docs.Doc_V30.DOC;
                    case 1:
                        return Docs.Doc_V31.DOC;
                    case 2:
                        return Docs.Doc_V32.DOC;
                    case 3:
                        return Docs.Doc_V33.DOC;
                    case 4:
                        return Docs.Doc_V34.DOC;
                }

                break;
            default:
                break;
        }

        return string.Empty;
    }

Example of version 3.1

{
    /// <summary>V3.1 Markdown documentation.</summary>
    public const string DOC = @"
__**v3.1 Change Log**__

**Notes**

* Added lookup for Budget Categories.

* Added lookup for Activity Areas which includes Modules and Interventions.

* Added detailed budget data at an implementation period level.  This data can be aggregated up to any level.

* Bug fixes and performance improvements.

**Breaking Changes**

* There are no breaking changes for this release.

**Published**

19-NOV-2019";
}

[commonsensesoftware]

To elaborate just a bit further, I want to make it clear that you can have complex documentation in the XML Comments. Swashbuckle does not appear to translate all of the XML Comment tags to HTML. You can find another way or use embedded HTML. I'm unsure if Markdown works, but you can certainly document with literal Markdown as well. It would look like this:

/// <summary>
/// Represents a RESTful service of orders.
/// <br/><br/>
/// <b>Notes</b>
/// <ul>
///  <li>Bug fixes and performance improvements.</li>
///  <li>Added lookup.</li>
///  <li>This data can be aggregated up to any level.</li>
/// </ul>
/// <b>Breaking Changes</b>
/// <ul>
///  <li>There are no breaking changes for this release.</li>
/// </ul>
/// <b>Published</b>
/// <br/><br/>
/// 19-NOV-2019
/// </summary>
[ApiVersion(2.0)]
[Route("[controller]")]
public class OrdersController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

The output is then:

To include the controller <summary> content, you must also update your configuration with:

options.IncludeXmlComments( filePath, includeControllerXmlComments: true );

If you want overall comments for an API version set, then building a custom description is the only way I know. There is no concept to give an API group a description in the API Explorer. ApiDescriptionGroup only has a GroupName and Items collection of all ApiDescription instances in the group.