Skip to content
This repository was archived by the owner on Nov 16, 2023. It is now read-only.

C# Comment Tag Guide

Jump to bottom
Shweta Patil edited this page Oct 30, 2018 · 14 revisions

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">)
  • <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.

<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 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>
  1. 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>
  1. 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>

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. |

Clone this wiki locally