C# Comment Tag Guide

All tags are optional EXCEPT <url> and <verb>.

<url>

Example: <url>http://localhost:9000/V1/samples</url>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Relative path in Text	#/paths	For example, if the text is http://localhost:9000/V1/samples, then only /V1/samples is parsed into the path identifier.

<verb>

Example: <verb>GET</verb>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}

<group>

Example: <group>Sample V1</group>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}/{method}/tags

<summary>

Example: <summary>API summary<summary>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}/{method}/summary

<remarks>

Example: <remarks>API description<remarks>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}/{method}/description

<param> when in attribute is not body

Example: <param name="sampleHeaderParam1" cref="float" in="header">Header param 1</param>

Alternate tag(s) allowed:

• <queryParam> (equivalent to <param in="query">)
• <headerParam> (equivalent to <param in="header">)
• <pathParam> (equivalent to <param in="path">)

Remarks: If in attribute is not given but the parameter name is present in the <url> tag, the processor will also automatically populate the in attribute for that <param> tag as either path or query as appropriate.

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}/{method}/parameters/{i}/description
Attribute name	#/paths/{path}/{method}/parameters/{i}/name
Attribute in	#/paths/{path}/{method}/parameters/{i}/in
Attribute cref	#/paths/{path}/{method}/parameters/{i}/schema	The type provided can be a primitive type or a class. The reader will resolve it using the given DLLs and create an appropriate schema object for it.

<param> when in attribute is body

Example: <param name="sampleObject" in="body"><see cref="SampleObject1"/>Sample object</param>

Alternate tag(s) allowed: <requestType>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Text	#/paths/{path}/{method}/requestBody/description
Attribute type	#/paths/{path}/{method}/requestBody/content	Media type e.g. application/json
Attribute cref of inner node <see>	#/paths/{path}/{method}/requestBody/content/{type}/schema	The type provided can be a primitive type or a class. The reader will resolve it using the given DLLs and create an appropriate schema object for it.

<response>

Example: <response code="200"><see cref="SampleObject1"/>The sample object updated</response>

Alternate tag(s) allowed: <responseType>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Attribute code	#/paths/{path}/{method}/responses	The HTTP Status code e.g. 200
Attribute type	#/paths/{path}/{method}/responses/{statusCode}/content	Media type e.g. application/json
Attribute cref of inner node <see>	#/paths/{path}/{method}/responses/{statusCode}/content/{type}/schema	The type provided can be a primitive type or a class. The reader will resolve it using the given DLLs and create an appropriate schema object for it.

<header> for response header

Example: <header name="TestHeader" cref="string"><description>Test Header</description></header>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Attribute name	#/paths/{path}/{method}/responses/{code}/headers/{string}	Unique string which will be used as the key to map a header name to its definition
Attribute description	#/paths/{path}/{method}/responses/{code}/headers/{string}	Description of the header
Attribute cref	#/paths/{path}/{method}/responses/{code}/headers/{string}/schema	The type provided can be a primitive type or a class. The reader will resolve it using the given DLLs and create an appropriate schema object for it.

<example>

Example tag can be used as nested tag for any param or response tag.

Example:

1. <example name="Example one"><value>First example</value></example>
2. <example><value><see cref="Examples.SampleObject1Example"/></value></example>
3. <example><summary>Test Example</summary><url>https://example</url></example>

Part of the tag	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Attribute name	#/paths/{path}/{method}/requestBody/examples/{i}	Unique string which will be used as the key to map a example name to its value
Attribute summary	#/paths/{path}/{method}/requestBody/examples/{i}/summary	Summary of the example
Attribute value	#/paths/{path}/{method}/requestBody/examples/{i}/value	Embedded literal example.
Attribute url	#/paths/{path}/{method}/requestBody/examples/{i}/externalValue	A URL that points to the literal example.

The value and url tag are mutually exclusive.