microsoft
/
OpenAPI.NET.CSharpAnnotations
зеркало из https://github.com/microsoft/OpenAPI.NET.CSharpAnnotations.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность
Страница: C# Comment Samples
Страницы
Advanced Configuration XML C# Comment Samples C# Comment Tag Guide Home
0 C# Comment Samples
Shweta Patil редактировал(а) эту страницу 2019-05-14 15:04:24 -07:00
Убрать экранирование Экранировать
Содержание
Этот файл содержит неоднозначные символы Юникода!

Этот файл содержит неоднозначные символы Юникода, которые могут быть перепутаны с другими в текущей локали. Если это намеренно, можете спокойно проигнорировать это предупреждение. Используйте кнопку Экранировать, чтобы подсветить эти символы.

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" required="true">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>
  • To set the Content-Type of Request body, use type attribute
///<param name="sampleObject" in="body" type="application/x-www-form-urlencoded"><see cref="SampleObject1"/>Sample object</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"/>
///     <header name="X-Header" cref="string"><description>Test Header</description></header>
/// Sample objects
/// </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"/>
///     <example>
///         <value>
///         {\"samplePropertyBool\":true,\"samplePropertyEnum\":\"SampleEnumValue2\"}
///         </value>
///         <summary>
///         Sample Example
///         </summary>
///     </example>
///     Sample object
/// </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"/>
///     <example>
///         <url>
///         http://example.org/petapi-examples/openapi.json#/components/examples/name-example
///         </url>
///         Sample Example
///     </example>
///     Sample Header
/// </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"/>
///     <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>
///     Sample object
/// </param>

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>
  1. For ApiKey type
/// <security type="apiKey" name="apiKey">
    ///     <description>Test security</description>
    ///     <in>query</in>
    /// </security>