Feature Request: More support for xml comments

[SebastianStehle]

Hi,

I moved from SwaggerUI to Redoc because i have much space for the description and there is a lot to document.

Therefore I also like to use xml comments, because it is easier to add markup there.

I am missing xml comments in two places:

1. Tag Description:

Usually I have a Tag = Controller model, it would be awesome to make something:

/// <summary>
/// Query and manages users.
/// 
/// Please note:
/// * Users ...
/// * Users ...
/// * Users ...
/// * Users ...
///
/// You need one of the following role: Owner, Editor, use XYZ to manage permissions.
/// </summary>
[SwaggerTags("Users")]
public class UsersController {
}

Btw: I think you should remove the "Controller" suffix from the default tag.

2. Response Codes

I Would like to have the swashbuckle solution:

/// <response code="201">Account created</response>
/// <response code="400">Username already in use</response>

As a workaround I implemented a processor that parses the result

/// <result>
/// 200 => Account created
/// 400 => Username already in use
/// </result>

But it cannot handle multiline yet.

What do you think?

[RicoSuter]

You can already use [SwaggerResponse(201, typeof(...), Description = "foobar")]

[SebastianStehle]

I know, for some status codes there might be a lot of reasons, e.g. 400, therefore I would like to have multiple lines. And also do not like to have my descriptions spread acrosss attributes and comments.

[RicoSuter]

Can we close this: https://github.com/NSwag/NSwag/issues/442 and discuss here?

To implement your features, we need to enhance: https://github.com/NJsonSchema/NJsonSchema/blob/master/src/NJsonSchema/Infrastructure/XmlDocumentationExtensions.cs

[SebastianStehle]

We can, but I think #442 is a bug, because you cannot write correct markdown code at the moment. This task is more a feature request.

[RicoSuter]

With https://github.com/NJsonSchema/NJsonSchema/commit/570e8b4c08364953be9b4681a48320687e074558 it is possible to do 1.

[RicoSuter]

2.: The question is: What response types should be used when the responses are only defined in xml doc?