Create standard for XML tags that target REST APIs

[captainsafia]

I'm writing up this issue to capture a though I have around creating a standardizeds extension of XML tags that can be used specifically to document REST APIs.

This requirement comes out of the scenario to support XML doc comments in OpenAPI comments. At the moment, the conventions that we use for which tags are used to map to which OpenAPI elements are based on a mix of intuition and prior art.

Since there are several implementations of tools that derive OpenAPI information from XML docs we should consider creating a standard set that can be used specifically for annotation methods that map to REST APIs. Some examples:

• <response code="200"> exists as a convention for description response types for different HTTP status codes
• <example content-type="application/json"> as a new convention for examples that map to a specific content-type
• Clarity around how <summary>, <description>, and <value> map to Summary and Description in the OpenAPI document
• <tags> as a convention for identifying the tags associated with a type

We probably want this to be specific enough that it is helpful for OpenAPI but not so specific that it is overfit for that particular scenario.

Tagging folks who might be interested in the space: @martincostello @desjoerd @mikekistler

[martincostello]

This seems reasonable to me.

Maybe it's also worth standardising and few other related things, such as how whitespace, newlines etc. are processed? There's been debate about these things in Swashbuckle's own support for XML documentation.

[desjoerd]

I like it.

It should also note whether something is allowed to be repeated (for <example> we could allow multiple as we can add multiple examples to OpenApi 3.1).