Create standard for XML tags that target REST APIs
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 281
Description
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:
- `` exists as a convention for description response types for different HTTP status codes
- `` as a new convention for examples that map to a specific content-type
- Clarity around how ``, ``, and `` map to `Summary` and `Description` in the OpenAPI document
- `` 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
Contributor guide
Assessment
This issue has not been assessed yet.