利用swagger建立互動式API文件

2015年12月28日 星期一

最近在寫Web API程式,通常都會搭配Help Page來使用,可以建立文件方便查詢,但是如果要測試API,則都會使用Fiddle或是PostMan來做測試,同事有介紹我一套叫Swagger的套件,它不只能產生文件,也可以在網頁上直接測試,是不是超棒的,以下是記錄我安裝的過程以及使用方法,我是用新專案來做範例


1.建立新專案
2.選擇Web API
3.使用NuGet來下載Swagger套件


4.安裝完成後,在專案上按右鍵,選擇屬性

5.選擇產生文件要放置的地方

6.開啟App_Start\SwaggerConfig.cs,打開註解處

7.實作GetXmlCommentsPath()方法

8.測試時,只要執行網站並在後面輸入\swagger即可開始頁面

9.可直接展開方法,並做測試,執行後可看到結果





以上就是基本的swagger套件使用方式。
最後附近github位址:https://github.com/domaindrivendev/Swashbuckle

Read more...

為Enum加入取得Description Extension方法

2015年12月22日 星期二

在使用Enum時,有時候需要定義說明文字以利在UI上呈現,所以可以加入屬性Description,於是在網路上找了一下,結果只有找到取得名稱的方式,如下所示
 
using System;

public class GetNameTest {
    enum Colors { Red, Green, Blue, Yellow };
    enum Styles { Plaid, Striped, Tartan, Corduroy };

    public static void Main() {
        Console.WriteLine("The 4th value of the Colors Enum is {0}", Enum.GetName(typeof(Colors), 3));
        Console.WriteLine("The 4th value of the Styles Enum is {0}", Enum.GetName(typeof(Styles), 3));
    }
}


來源:https://msdn.microsoft.com/zh-tw/library/system.enum.getname(v=vs.110).aspx


所以只好自已寫擴充方法來新增

 
public static class HelpExtensions
{
 public static string GetEnumDescription(this Enum value)
 {
  FieldInfo fi = value.GetType().GetField(value.ToString());

  DescriptionAttribute[] attributes = (DescriptionAttribute[])fi.GetCustomAttributes(typeof(DescriptionAttribute), false);
  //若取不到屬性,則取名稱
  if ((attributes != null) && (attributes.Length > 0))
   return attributes[0].Description;
  else
   return value.ToString();
 }
}

public enum MessageType
{
    [Description("Create")]
    Creation = 1,
    [Description("Update")]
    Updating = 2,
    [Description("Del")]
    Deletion = 3,
    [Description("Select")]
    Selection = 4
}

//使用方式
var messageType = MessageType.Deletion.GetEnumDescription();
Console.WriteLine("Ouput:" + messageType);
//顯示結果
//Output:Del

Read more...