app後端開發一:swagger-ui教程-構建api介面文件工具

app後端開發一:swagger-ui教程-構建api介面文件工具

宣告


之前寫過關於app後端開發的一系列文章,那是我第一次做app後端開發,存在很多不足,本想好好修改一下,想想還是重新寫吧,這樣子也能讓我部落格文章看起來多一點嘛,萬一以後找工作,別人一看我部落格這麼多內容,是不是很屌?
這次文章先從構建resetful風格的api文件工具開始。沒有一個好的文件工具,在app前端人員開發過程中會導致開發效率極低,而且時不時的,他們就來找你跟他們斷點一下。

我的文件經歷

這裡先不討論我的資料傳輸是否合理,僅僅以這些資料作為一個演示。後面會有專門的章節進行app資料傳輸加密的講解。


  1. 在我第一次開發app後端的時候,使用的word文件,就是我先將所有資料格式定義好,會返回什麼樣的資料寫好。前端人員照這個來進行開發。貼一張圖吧:
    這裡寫圖片描述
    PS:存在的問題:①介面改動時,不易被識別。②維護困難,不便於查詢。③前端開發不能進行測試。(如果還要寫缺點,有5K 字可以寫出來,就省略了哈)
  2. 在我開發第二個APP的後端時,先自己寫了一個簡易的app介面管理系統,用來後端釋出介面,以及前端人員檢視。效果如圖:
    這裡寫圖片描述
    PS:優點:①如果有多個前端人員,可以保證大家看到的是同一份文件。②通過介面的版本標識,方便大家檢視是否修改,優點等等省略。缺點:①不能夠進行線上介面測試,需要藉助poster外掛。
  3. 現在給大家要推薦下我利用一天時間改造的swagger-ui的中文版了。本來英文就非常好了,只是為了瞭解一下這個東東,順手給他改成中文版了,也做為自己第一個github的專案吧。還是先上效果圖吧:
    介面模組介面:
    這裡寫圖片描述
    介面列表介面:
    這裡寫圖片描述
    某個介面介面:
    這裡寫圖片描述

OK,貼圖到此為止啦,如果還沒有看夠的同學,給你們一個連線,自己去試試:
swagger-ui中文版地址:http://helei112g.github.io/swagger-ui/


相信經過剛剛的體驗,不需要我說它的強大與便利了吧?不僅僅可以通過它立即進行線上測試,還可以根據返回的json它自動構建成model。便於你做決策。好處我就不說了,反正自從用了它,我們的前端腰不酸,腿也不痛了。寫起程式碼來也精神了。

哦,最重要的,下載地址:
https://github.com/helei112g/swagger-ui
如果覺得不錯,麻煩給個start吧,給我的鼓勵一下下,謝謝!

app後端開發系列文章目錄