dotnet / dotnet/aspnetcore

Create standard for XML tags that target REST APIs

Open
#63,165 4 comments 2 reactions 0 assignees View on GitHub
area-minimal feature-openapi
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.