Duran 研究筆記 - 微軟相關技術

回想約三年前的第一份工作，在 Java Application 或 Android App 專案開發過程中，與其他開
發者溝通與確認WebAPI格式是必須且非常繁瑣的。雖然工作內容不難，但常常因為一些細節
耗費相當多的時間。
在開發過程中，必須要了解WebAPI使用方式、解析或回傳不同格式資料(XML、JSON)、需
要保持資料一致性...等。所以我們必須以文件紀錄這些資訊，並作為開發者之間溝通的方式。

早期紀錄的方式，以簡單的Google document或Word方式紀錄與說明 WebAPI，記錄範例如
下：

方法：GET
參數格式：String
參數名稱：Id
回傳資料格式：JSON
回傳資料內容：{ "name" : "duran" }

這種紀錄方式有些缺點：
1.人工撰寫文件：非常花費時間。
2.文字記錄錯誤：因為人工輸入，運氣不好可能因為錯字花費很多時間。
3.無法即時測試：Get可能方便測試，輸入網址即可測試，如果是Post呢? 如果有10個參數呢?
                               如果超長JSON呢?
4.難以紀錄歷程：問題比較小，使用版本控管軟體可以解決這個問題。
5.文件不夠詳細：可能又要找WebAPI開發者討論，花費時間。


換了新環境，當然也要入境隨俗的偷學新東西！！ 而不能像過去一樣花費時間在鎖碎的
問題上！！
今天這篇主要簡單介紹swashbuckle，一個整合ApiExplorer and Swagger/swagger-ui，容易安裝、

容易維護WebAPI與可以進行測試的好用套件。

 

這篇文章將同時發佈在點部落與個人blogger


 

Install Package：

Step.2 選擇"ASP .NET 4 Web Application", 輸入專案名稱"SwaggerDemo"
           Select "ASP .NET 4 Web Application", Enter "SwaggerDemo" in Project Name textbox


Step.3 選擇Web API
           Select Web API


Step.4 選擇 TOOLS >> NuGet Package Manager >> Manage NuGet Packages for Solution...
           Select TOOLS >> NuGet Package Manager >> Manage NuGet Packages for Solution...


Step.5 輸入swashbuckle進行搜尋，點選Install安裝"swashbuckle - Swagger for WebApi"
           Enter "swashbuckle" in search box, and click Install button to install
           "swashbuckle - Swagger for WebApi"


Step.6 啟動專案，瀏覽器上輸入網址"http://localhost:xxxxx/swagger/" (xxxxx是port)
           Start Project, and enter url "http://localhost:xxxxx/swagger/" on browser (xxxxx is port)


Step 7.你會看到Values WebAPI所有的服務，如下圖：
            You can see all web service of  "Values WebAPI":



Step.8 展開"/api/Values"，點選"Try it out" , 你將會看到測試結果
           Expand  "/api/Values", click "Try it out", you will see the result

Step.8 展開"/api/Values/{Id}"，輸入資料並點選"Try it out" , 你將會看到測試結果
           Expand  "/api/Values", Enter parameters and click "Try it out", you will see the result

 

 

SwaggerReponse：

[SwaggerResponse(HttpStatusCode.OK, @"retrun vaule", typeof(bool))]
[SwaggerResponse(HttpStatusCode.InternalServerError, @"Server error", typeof(bool))]
[SwaggerResponse(HttpStatusCode.MethodNotAllowed, @"Invalid input", typeof(bool))]

 

XmlComments：

c.IncludeXmlComments(string.Format(@"{0}\App_Data\SwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));

 

範例程式下載:

https://dl.dropboxusercontent.com/u/13585157/SwaggerDemo.zip

 

 

參考資料：

http://swagger.io/

http://www.wmpratt.com/swagger-and-asp-net-web-api-part-1/