How do you specify controller descriptions?

[drullo]

I have a .NET Core web API written in C# and I have been unable to get NSwag to include descriptions for the controllers. I have tried a DescriptionAttribute and a standard <summary> comment. My actions and parameters are being properly documented, including description (summary) and remarks.

Also, I see from the documentation that there's a recommendation to set IsAspNetCore to true. Where/how do you set that value and is it a current requirement? I'm not sure what the implications are of the "reflection based generator eventually being deprecated" - does that mean that I need to change my approach to controller documentation somehow?

[RicoSuter]

You should integrate with the middleware and use the api explorer based generator for asp.net core

[RicoSuter]

You need to enable xml docs output in the project...

[drullo]

@RSuter , I do have xml doc output enabled in the project. Without it, I wasn't getting any summary/parameter documentation at all. It is enabled and it is working for controller actions. But what I'm lacking are descriptions on the actual controllers themselves.

For clarification of what I'm looking for, the demo at http://petstore.swagger.io includes descriptions on each of the 3 controllers, as well as additional information displayed on the right.

[RicoSuter]

I think this might be a bug

[RicoSuter]

But what I'm lacking are descriptions on the actual controllers themselves.

The controller descriptions cannot be preserved because "controllers" is not a concept of Swagger and only internally generated/grouped by NSwag... We'd need to enhance the spec with custom data with controller info etc.

[BlackfinchGroup]

Guessing this feature isn't being added anytime soon?

[RicoSuter]

Probably not, as custom extensions do not bring much value as they are not understood by consumers (external client gens, etc.)

But you can do this manually with custom operation processors: https://github.com/RicoSuter/NSwag/wiki/Document-Processors-and-Operation-Processors

[BlackfinchGroup]

Could not controllers be mapped to the tags concept in swagger.
For example in the petstore yaml - https://petstore.swagger.io/ - this creates grouped endpoints, similar in concept to controllers.

tags:
- name: "pet"
  description: "Everything about your Pets"
paths:
  /pet:
    post:
      tags:
      - "pet"

[RicoSuter]

I think this is already the case except that the description is not used, can you create a PR?

[tux1337]

I tested it these times, and it is still not working with the <summary> tag. Do I'm something wrong or is still an PR needed?

[SmRiley]

now,u can use that enable controller description:

services.AddSwaggerDocument(c =>
  {
      c.UseControllerSummaryAsTagDescription = true;
  });