使用swagger實現web api線上介面文檔

来源:http://www.cnblogs.com/4littleProgrammer/archive/2017/04/15/6713627.html
-Advertisement-
Play Games

一、前言 通常我們的項目會包含許多對外的介面,這些介面都需要文檔化,標準的介面描述文檔需要描述介面的地址、參數、返回值、備註等等;像我們以前的做法是寫在word/excel,通常是按模塊劃分,例如一個模塊包含n個介面,就形成一個文檔,然後再用版本控制管理。這樣做的缺點是: 1.不夠直觀,每次打開文檔 ...


一、前言

  通常我們的項目會包含許多對外的介面,這些介面都需要文檔化,標準的介面描述文檔需要描述介面的地址、參數、返回值、備註等等;像我們以前的做法是寫在word/excel,通常是按模塊劃分,例如一個模塊包含n個介面,就形成一個文檔,然後再用版本控制管理。這樣做的缺點是:

1.不夠直觀,每次打開文檔查看介面很麻煩

2.文檔的維護難度大

3.調用方和測試人員使用麻煩,需要先去找介面,在用相應的工具測試(例如使用瀏覽器還可能要安裝插件)

  我們希望是可以直接線上瀏覽,然後直接用瀏覽器測試。而介面的詳細描述都在程式里用註釋完成。swagger就可以完成這個工作(ps好像很多開發人員都還不知道這個東西。。。)。

二、使用Swagger

  Swagger 是一款RESTFUL介面的文檔線上自動生成+功能測試功能軟體。

  在web api 使用swagger可以說非常簡單,不需要編寫任何代碼,完全依賴於插件。具體步驟如下:

    1.新建一個web api項目

  

  2.使用nuget添加Swashbuckle

  

  3.完成

  沒錯,就是這麼簡單!運行項目,轉到地址 http://localhost:57700/swagger/ui/index 會看到如下頁面,這是預設添加的兩個apicontroller:  

  這個時候介面還沒有具體的描述信息等,例如我們給ValuesController.Get添加註釋描述,在頁面上還是沒有顯示出來。需要按照如下步驟實現:

  1. 在app_start 下 SwaggerConfig 大100行的位置找到 //c.IncludeXmlComments(GetXmlCommentsPath()); 如下註釋,改為:c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); (註意去掉註釋了

  2. 在SwaggerConfig添加一個方法代碼:

        protected static string GetXmlCommentsPath(string name)
        {
            return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
        }

  3. 修改項目生成,在bin下對應的xml文件可以看到具體的描述文檔,如下:

  

  重新生成項目,就要可以看到完整的介面描述了。例如我們心中一個TestController如下:

    /// <summary>
    /// 測試控制器
    /// </summary>
    public class TestController : ApiController
    {
        /// <summary>
        /// 測試Get方法
        /// </summary>
        /// <remarks>測試Get方法</remarks>
        /// <returns></returns>
        [HttpGet]
        public string Get()
        {
            return "Get";
        }

        /// <summary>
        /// 測試Post方法
        /// </summary>
        /// <param name="name">姓名</param>
        /// <param name="age">年齡</param>
        /// <remarks>測試Post方法</remarks>
        /// <returns></returns>
        [HttpPost]
        public string Post(string name, int age)
        {
            return name + age.ToString();
        }
    }

  生成的頁面如下,可以看到介面的描述,點擊Try it out 即可調用:

  

三、非依賴代碼

  上面的方式依賴於Swashbuckle包,它已經包含了Swagger-UI組件。我們的代碼需要引入這個包,實際上也可以不需要在項目中引入,單獨部署Swagger,包括Swagger-Ui(api展示) 和 Swagger-Editor(線上編輯器),它需要依賴nodejs環境,所以需要先按照nodejs。部署其實也很簡單,例如這是我部署的結果:

  swagger-editor:  

  swagger-ui:

  編輯後只需要將文件保存為json文件,然後拷貝到指定的目錄即可。這個部署也非常簡單,具體可以參照:

  1.http://www.raye.wang/2016/09/29/swaggerhuan-jing-da-jian-zhi-fei-yi-lai-dai-ma-fa/?utm_source=tuicool&utm_medium=referral

  2.http://blog.csdn.net/ron03129596/article/details/53559803

四、總結

  規範化api的編寫和註釋,以及標準化文檔,對於團隊的開發效率有很大的提升,也有利於項目的維護。例如使用線上介面文檔後,測試人員測試只需要在頁面輸入參數,點擊調用就可以看到調用結果。

  swagger 也有線上版的,不需要要自己部署。實際上非代碼依賴的方式反而更麻煩,使用代碼依賴的方法可以像平時我們寫註釋一樣就可以,既能在程式里描述,方便開發人員瞭解介面功能,也可以在線上展示,發佈調用方和測試人員調用。


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 轉自:http://blog.163.com/m13864039250_1/blog/static/2138652482015283397609/ 用Fluent API 配置/映射屬性和類型 簡介 通常通過重寫派生DbContext 上的OnModelCreating 方法來訪問Code Firs ...
  • 在一些數據的即時查詢場景中,我們可能需要對輸入信息進行模糊查詢併進行選擇,例如在一些文本輸入場景,如輸入某個站點編碼或者設備編碼,然後獲取符合的列表供用戶選擇的場景,本篇隨筆介紹在DevExpress程式中使用PopupContainerEdit和PopupContainer實現數據展示。 ...
  • Rookey.Frame v1.0經過一年時間的修改及沉澱,穩定版終於問世了,此版本經過上線系統驗證,各個功能點都經過終端用戶驗證並持續優化,主要優化以下幾個方面: 1.性能較原來提升3倍之多 2.修複BUG數達1000+上 3.模塊緩存即時生效無需手動刷新緩存 4.增加可配置的任務調度功能 5.表 ...
  • 一.IIS部署基本問題 將項目部署部署到IIS時,啟動網站常會遇到頁面報錯not found 403 可能原因: 1.應用程式池.Net Framework版本不對,解決方法打開控制面板-->管理工具-->Internet信息服務(IIS)管理器,打開應用程式池選擇項目的應用程式,配置為相應版本; ...
  • net core cli 是快速創建模板項目 1. 安裝CLI 參考: https://www.hanselman.com/blog/dotnetNewAngularAndDotnetNewReact.aspx 視頻參考: https://www.youtube.com/channel/UC_R2R ...
  • row.Table.Columns.Contains( "fieldname ") ...
  • 寫在開頭:看了一些視頻教程,感覺OD為什麼別人學個破解那麼容易,我就那麼難了呢,可能是沒有那麼多時間吧。 解釋:個人見解:所謂記憶體補丁,即:通過修改運行程式的內容,來達到某種目的的操作。修改使用OpenProcess打開,WriteProcessMemory寫入,CloseHandle關閉。部分需要 ...
  • 在程式設計 之 C#實現《拼圖游戲》 (上)中,上傳了各模塊代碼,在本文中將詳細剖析原理,使讀者更容易理解並學習,程式有諸多問題,歡迎指出,共同學習成長! ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發(一):使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說,近來想嘗試開發一款安卓APP,考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP,畢竟是使用Visual Studio開發工具,使用起來也比較的順手,結合微軟官方的教程進行了安卓 ...
  • 前言 QuestPDF 是一個開源 .NET 庫,用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫,它徹底改變了我們生成 PDF 文檔的方 ...
  • 項目地址 項目後端地址: https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址: ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址: http://tree ...
  • 話不多說,直接開乾 一.下載 1.官方鏈接下載: https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe,運行開始下載SQL server; 二. ...
  • 前言 隨著物聯網(IoT)技術的迅猛發展,MQTT(消息隊列遙測傳輸)協議憑藉其輕量級和高效性,已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫,為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog支持多種接收器用於日誌存儲,增強器用於添加屬性,LogContext管理動態屬性,支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項,適用於不同需求。 ...
  • 目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據,爬取信息時需要模擬瀏覽器行為,否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下: 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • 1.前言 什麼是熱更新 游戲或者軟體更新時,無需重新下載客戶端進行安裝,而是在應用程式啟動的情況下,在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR,Xlua,ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles,Addressable, ...
  • 本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺,其實像阿裡雲,騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後,它會送 ...
  • 通過以下方式可以高效,並保證數據同步的可靠性 1.API設計 使用RESTful設計,確保API端點明確,並使用適當的HTTP方法(如POST用於創建,PUT用於更新)。 設計清晰的請求和響應模型,以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證,確保接收到的數據符合預期格 ...