[Asp .Net MVC][WebAPI] Swashbuckle - Swagger Framework for API

熱門文章 (Popular Post)

Posted by : Duran Hsieh 10月 27, 2015

前言:

回想約三年前的第一份工作,在 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.1 開啟Visual Studio,點選New Project...
           Open Visual Studio,  Click New Project...



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:

您可以加入SwaggerReponse Annotations 表示回應呈現訊息(Reponse Message)
You can add SwaggerReponse Annotations for Reponse Message
[SwaggerResponse(HttpStatusCode.OK, @"retrun vaule", typeof(bool))]
[SwaggerResponse(HttpStatusCode.InternalServerError, @"Server error", typeof(bool))]
[SwaggerResponse(HttpStatusCode.MethodNotAllowed, @"Invalid input", typeof(bool))]




XmlComments:

您可以藉由xml comments來讓API 文件更詳細。
You can make the API doucment completely by xml comments

Step.1 右鍵點選solution >> properties
            Right click solution >> properties


Step.2 在"Build"頁面,勾選"XML doucmentation"並輸入路徑"App_Data\SwaggerDemo.XML"
            In Build tab, Check "XML doucmentation" and enter "App_Data\SwaggerDemo.XML" in 
            path textbox



Step.3 開啟App_Start\SwaggerConfig.cs,輸入下列指令
           Open App_Start\SwaggerConfig.cs,add the code as shown
c.IncludeXmlComments(string.Format(@"{0}\App_Data\SwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory));

Step.4 加入xml comments
           Add xml comments


Step.5 執行專案
           Start Project



範例程式下載:

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


參考資料:

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







Leave a Reply

Subscribe to Posts | Subscribe to Comments

- Copyright © Duran Hsieh @ Matsurigoto - Date A Live - Powered by Blogger - Designed by Johanes Djogan -