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

C# Comment Samples

Jump to bottom
Shweta Patil edited this page Jul 6, 2018 · 8 revisions

Url

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

Path Parameter

Examples:

  • Type of parameter is a primitive type

<param name="samplePathParam1" cref="float" in="path">Path param 1</param>

  • Type of parameter is a custom type

<param name="samplePathParam1" cref="SampleObject1" in="path">Path param 1</param>

Query Parameter

  • Type of parameter is a primitive type

<param name="sampleQueryParam1" cref="float" in="query">Query param 1</param>

  • Type of parameter is a custom type

<param name="sampleQueryParam1" cref="SampleObject1" in="query">Query param 1</param>

Header

  • Type of parameter is a primitive type

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

  • Type of parameter is a custom type

<param name="sampleHeaderParam1" cref="SampleObject1" in="header">Header param 1</param>

Request Body

  • Type of parameter is a primitive type

<param name="sampleRequestContract" in="body"><see cref="string"/>Request contract</param>

  • Type of parameter is a custom type

<param name="sampleRequestContract" in="body"><see cref="SampleObject1"/>Request contract</param>

  • Type of parameter is a collection of custom type
/// <param name="sampleRequestContract" in="body">
/// <see cref="List{T}"/>
/// where T is <see cref="SampleObject2"/>
/// Request contract
/// </param>
  • Type of parameter is a Dictionary of custom type
/// <param name="sampleRequestContract" in="body">
/// <see cref="Dictionary{TKey, TValue}"/>
/// where TKey is <see cref="SampleObject1"/>
/// where TValue is <see cref="SampleObject4"/>
/// Request contract
/// </param>
  • Type of parameter is something like List<ISampleObject4<SampleObject1, SampleObject4>>
/// <param name="sampleRequestContract" in="body">
/// <see cref="List{T}"/>
/// where T is <see cref="ISampleObject4{T1,T2}"/>
/// where T1 is <see cref="SampleObject1"/>
/// where T2 is <see cref="SampleObject4"/>
/// Request contract
/// </param>

Response

  • 200 response with Type a primitive type

<response code="200"><see cref="string"/>Success</param>

  • 200 response with custom type

<response code="200"><see cref="SampleResponseObject"/>Success</param>

  • Multiple response codes(200,400)
/// <response code="200">
/// <see cref="List{T}"/>
/// where T is <see cref="ISampleObject4{T1,T2}"/>
/// where T1 is <see cref="SampleObject1"/>
/// where T2 is <see cref="SampleObject4"/>
/// List of sample objects
/// </response>
/// <response code="400"><see cref="string"/>Bad request</response>
  • Polymorphic response code(i.e. if a response code can be of multiple types)
/// <response code="200"><see cref="string"/></response>
/// <response code="200">
/// <see cref="List{T}"/>/// where T is <see cref="SampleObject1"/>
/// List of sample objects
/// </response>
  • Response with complex types please refer to see cref examples for Requst Contract

Response Header

"name" should be unique across header tags as its used as key for headers map.

/// <response code="200">
/// <see cref="string"/>
/// Sample objects
///     <header name="X-Header" cref="string"><description>Test Header</description></header>
/// </response>

Example

Example tag can be nested inside any param, response tag.

  • For a simple example that can be represented inline of tag (this can’t be used for content type application/xml)
/// <param name="sampleObject" in="body">
///     <see cref="SampleObject3"/>
///     Sample object
///     <example>
///         <value>
///         {\"samplePropertyBool\":true,\"samplePropertyEnum\":\"SampleEnumValue2\"}
///         </value>
///         <summary>
///         Sample Example
///         </summary>
///     </example>
/// </param>
  • For examples that can't be represented inline, include a static string field like below and reference it as cref and generation library will use reflection to fetch the value of the field from the provided contract assemblies.
public static string example = "{\"samplePropertyBool\":true,\"samplePropertyEnum\":\"SampleEnumValue2\"}";

/// <response code="200">
///     <see cref="SampleObject1"/>
///     <example>
///         <value>
///             <see cref="SampleControllerV1.example"/>
///         </value>
///         <summary>
///         Sample Example
///         <summary>
///     </example>
/// </response>
  • To reference a url for example value
/// <param name="sampleHeader" in="header">
///     <see cref="string"/>
///     Sample Header
///     <example>
///         <url>
///         http://example.org/petapi-examples/openapi.json#/components/examples/name-example
///         </url>
///         Sample Example
///     </example>
/// </param>
  • To provide more than one example, name should be unique as its used as key for the examples map. If no name is provided generation library will generate one for you.
/// <param name="sampleObject" in="body">
///     <see cref="SampleObject3"/>
///     Sample object
///     <example name="example1">
///         <url>
///         http://example.org/petapi-examples/openapi.json#/components/examples/name-example
///         </url>
///     </example>
///     <example name="example2">
///         <url>
///         http://example.org/petapi-examples/openapi.json#/components/examples/name-example
///         </url>
///     </example>
/// </param>
Clone this wiki locally