2016年10月13日 星期四

【Swagger】活著的API規格書


所謂的工程師就是,【接手別人專案時,總是問怎麼沒有規格書? 自己開發專案時卻又不喜歡寫規格書】的一群人,本人也是一個極度不喜歡寫規格書的人,簡單說就是懶到極致,懶到深處無怨尤。而且常常改版時來匆匆忙忙,寫程式的時間都不夠了,誰還管你規格書有沒有更新,就這樣恍神個兩三次忘記回去更新規格,這本規格書就光榮列入公司十大(搞不好百大?)不可思議天書,可謂極度麻煩費時討厭.....

還好同事介紹了Swagger的用法,讓你邊開發程式時,規格就產生書產生出來了,而且還是本可以使用的規格書,讓你從今以後再也不用擔心規格書與實際規格脫鉤的問題,以下就筆記一下如何使用

Swagger-當開發完API時,規格書也就完成了!!
輸入的參數與說明也寫得清清楚楚
按下Try it Out後,可以馬上測試API跟觀看結果!!


使用步驟

  • 首先我先開一個WebAPI專案,然後寫一支簡單的API讓他可以運作
開一個WebAPI專案

新增一個新的TestSwaggerController




  • 開始撰寫幾個簡單的API跟輸入輸出參數


    public class testSwaggerGetParameter
    {
        /// <summary>
        /// 帳號
        /// </summary>
        /// <value>
        /// The identifier.
        /// </value>
        public string ID { get; set; }

        /// <summary>
        /// 密碼
        /// </summary>
        /// <value>
        /// The passWord.
        /// </value>
        public string PassWord { get; set; }
    }

   
    public class TestSwaggerController : ApiController
    {
        /// <summary>
        /// 測試Swagger的API
        /// </summary>
        /// <param name="parameter">The parameter.</param>
        /// <returns></returns>
        [HttpGet]
        [Route("api/testSwagger")]
        public HttpResponseMessage Get([FromUri]testSwaggerGetParameter parameter)
        {
            if (parameter != null &&
                parameter.ID == "toyo" && 
                parameter.PassWord == "123456")
            {
                return Request.CreateResponse(HttpStatusCode.OK, "帳號密碼正確");
            }

            return Request.CreateResponse(HttpStatusCode.OK, "帳號密碼錯誤摟!!!!!");
        }
    }



  • 接著先來測試API的運作是否正常

輸入正確的測試

輸入錯誤的測試



  • API都準備就緒後,來安裝Swagger吧

首先打開Nuget搜尋Swashbuckle並安裝



接著打開專案屬性,設定輸出XML說明格式



打開SwaggerConfig做些設定


在第一百行的地方把註解拿掉


在最下面補上以下程式碼



  • 重新執行WebAPI,並且在網址列輸入......./Swagger

看到API被輸出成規格了,參數的註解是跟著Summary的



來測試看看!!!





最後,Swagger雖然已經非常好用了,也能符合大部分的情境運用,但還是有些美中不足的地方,例如如果今天API部分資訊要帶在Header裡面傳給API,在預設產生的地方是沒有提供可以輸入的地方。

但慶幸的是Swagger可以很彈性的去改寫這張最後會產生的View,可以自己擴充需要的欄位,下一篇在來介紹如何客製化Swagger頁面!!!




參考文章



0 意見:

張貼留言