Swashbuckle.webapi: How do I add descriptions to resources?

[raaga123]

Our API is up and running well, but I haven't figured out how to add a description to each resource. Using the "summary" tag works for operations, but doesn't seem to work for resources.

(Sorry about the naive question, but I'm at my wits' end here.)

Thanks,
-- Lyn

[domaindrivendev]

In Swagger 2.0, each Operation is assigned one or more arbitrary Tags. The swagger-ui then uses the first tag of each Operation to group them in the UI. By default, SB sets "controller name" as a tag on each Operation, hence why you see the operations grouped by controller name.

However, from a Swagger perspective, this can be any arbitrary string you like. Instead of "controller name", you can assign your own custom grouping key (even one that includes a description). Check out the GroupActionsBy config option for more details.

[raaga123]

I don't think this is quite the question I asked. I'm happy with the grouping as it is -- I just want the resource ("controller name?") to be presented with a few words of description, as it is in the Pet Store sample application. I can't find any documentation on how to do this.

[domaindrivendev]

If you're referring to the description shown below ...

Then this is in fact related to the "grouping tag" I discussed above. If you look at the raw swagger json you'll see that some global tags are defined (incl. a description) and then each operation references the appropriate tag through their "tags" property.

Swagger 2.0 has no concept of a "resource description" or "controller name" ... instead it groups operations by tags.

A final note, the version of swagger-ui that's embedded with SB is a little behind what you're seeing in the demo and the tags are just strings. I'll get this updated as soon as I find some time. In the meantime though, you can achieve what you're seeing in the swagger demo by enriching the default tag with an additional description:

c.GroupActionsBy(apiDesc =>
{
    var controllerName = apiDescription.ActionDescriptor.ControllerDescriptor.ControllerName;
    return string.Format("{0} : {1}", controllerName, DictionaryOfDescriptions[controllerName]);
}

You would have to define the dictionary of descriptions or you could go a step further and define some custom attribute that you can place on each controller and then have the above lambda look at that (available through the ControllerDescriptor) to populate the description part.

[jfeston]

I have this snippet of code that works for me, to grab the summary from the controller's XML comments

c.GroupActionsBy(apiDesc =>
{
    var controllerName = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName;
    var controllerType = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.ToString();
    var member = XDocument.Load(GetXmlCommentsPath()).Root?.XPathSelectElement($"/doc/members/member[@name=\"T:{controllerType}\"]");
    return $"{controllerName} : {member?.XPathSelectElement("summary")?.Value}";
});