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" required="true">Header param 1</param>

Alternate tag(s) allowed:

• <queryParam> (equivalent to <param in="query">)
• <header> (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.
Attribute required	#/paths/{path}/{method}/parameters/{i}/required	Determines whether this parameter is mandatory.If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.

<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" type="application/json"><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 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.
Tagdescription	#/paths/{path}/{method}/responses/{code}/headers/{string}	Description of the header

<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
Tagsummary	#/paths/{path}/{method}/requestBody/examples/{i}/summary	Summary of the example
Tagvalue	#/paths/{path}/{method}/requestBody/examples/{i}/value	Embedded literal example.
Tagurl	#/paths/{path}/{method}/requestBody/examples/{i}/externalValue	A URL that points to the literal example.

The value and url tag are mutually exclusive.

<security>

Security tag can be used to document security schemes

Example:

1. For http type

    /// <security type="http" name="http-bearer">
    ///     <description>Test security</description>
    ///     <scheme>bearer</scheme>
    ///     <bearerFormat>JWT</bearerFormat>
    /// </security>

2. For OAuth type

    /// <security type="oauth2" name="oauth">
    ///     <description>Test security</description>
    ///     <flow type="implicit">
    ///         <authorizationUrl>https://example.com/api/oauth/dialog</authorizationUrl>
    ///         <refreshUrl>https://example.com/api/oauth/dialog</refreshUrl>
    ///         <scope name="scope1">
    ///             <description>Example flow description</description>
    ///         </scope>
    ///     </flow>
    /// </security>

3. For OpenIdConnect type

    /// <security type="openIdConnect" name="openIdConnect">
    ///     <description>Test security</description>
    ///     <openIdConnectUrl>https://example.com/api/oauth/dialog</openIdConnectUrl>
    ///     <scope name="scope1">
    ///         <description>Scope 1 description</description>    
    ///     </scope>
    ///     <scope name="scope2">
    ///         <description>Scope 2 description</description>    
    ///     </scope>
    /// </security>

4. For ApiKey type

    /// <security type="apiKey" name="apiKey">
    ///     <in>query</in>
    /// </security>

Part of the tag	Applied To Security Scheme Type	JSON pointer to corresponding OpenAPI document (V3.0) entity	Remarks
Attribute type in Tag security	http, apiKey,oauth2, openIdConnect	#/components/securitySchemes/{name}/type	REQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
Attribute name in Tag security	http, apiKey,oauth2, openIdConnect	#/components/securitySchemes/{name}	REQUIRED. The unique identifier to identify the name of the security scheme.
Tag description in Tag security	http, apiKey,oauth2, openIdConnect	#/components/securitySchemes/{name}/description	OPTIONAL. A short description for security scheme.
Tag openIdConnectUrl in Tag security	openIdConnect	#/components/securitySchemes/{name}/openIdConnectUrl	REQUIRED. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
Tag scheme in Tag security	http("bearer")	#/components/securitySchemes/{name}/scheme	REQUIRED. The name of the HTTP Authorization scheme to be used
Tag bearerFormat in Tag security	http	#/components/securitySchemes/{name}/bearerFormat	A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
Tag in in Tag security	apiKey	#/components/securitySchemes/{name}/in	REQUIRED. The location of the API key. Valid values are "query", "header" or "cookie".
Tag flow under Tag security	oauth2	#/components/securitySchemes/{name}/flows	REQUIRED. An tag containing configuration information for the flow types supported.
Attribute type in Tag flow	oauth2	#/components/securitySchemes/{name}/flows/{type	REQUIRED. Type of the flow. Valid values are "implicit", "password","clientCredentials","authorizationCode"
Tag authorizationUrl in Tag flow	oauth2 ("implicit", "authorizationCode")	#/components/securitySchemes/{name}/flows/{type}/authorizationUrl	REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of a URL.
Tag tokenUrl in Tag flow	oauth2 ("password", "clientCredentials", "authorizationCode")	#/components/securitySchemes/{name}/flows/{type}/tokenUrl	REQUIRED. The token URL to be used for this flow. This MUST be in the form of a URL.
Tag refreshUrl in Tag flow	oauth2	#/components/securitySchemes/{name}/flows/{type}/refreshUrl	OPTIONAL. The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
Tag scope under Tag flow	oauth2	#/components/securitySchemes/{name}/flows/{type}/scopes	REQUIRED. The available scopes for the OAuth2 security scheme.
Attribute name in Tag scope	oauth2	#/components/securitySchemes/{name}/flows/{type}/scopes	REQUIRED. The unique identifier to identify the name of the scope.
Tag description under Tag scope	oauth2	#/components/securitySchemes/{name}/flows/{type}/scopes/{name}/description	REQUIRED. A short description of the scope.