前言

隨著前后端分離開發(fā)模式的流行，接口對(duì)接、聯(lián)調(diào)成為常事，前端同事會(huì)經(jīng)常問：我需要調(diào)哪個(gè)接口？這個(gè)接口數(shù)據(jù)格式是啥？條件都傳啥？?對(duì)于一些緊急接口可能會(huì)采取溝通對(duì)接，然后補(bǔ)文檔，其他的都會(huì)回一句：看文檔。?那難道要一邊開發(fā)一邊寫文檔嗎？早些年是這樣的，但對(duì)于后端同事就很不自在了，代碼敲的正起勁，突然又要去寫文檔(不然前端同事會(huì)時(shí)刻催或是來溝通)，這樣效率顯然不是很高。而Swagger就能很舒服的解決問題(當(dāng)然也有其他方式，挑一個(gè)比較火的)，用Swagger大概會(huì)有以下好處：

• 良好的可視化界面，在線查看即可(可自定義)；
  

• 前后端對(duì)接方便，避免邊擼代碼邊寫文檔；
  

• 可以直接進(jìn)行API運(yùn)行，提高自測(cè)效率；

• 文檔生成方便，結(jié)合第三方API接口管理平臺(tái)(YApi等)輕松生成文檔(軟件文件備案需要好多文檔的)。不寫文檔，更多時(shí)間擼代碼~~~

正文

直接上案例演示，老規(guī)矩，還是熟悉的WebApi項(xiàng)目：

運(yùn)行演示：

如果注冊(cè)組件時(shí)設(shè)置的名稱和注冊(cè)中間件時(shí)設(shè)置的json地址中的名稱不一樣，就會(huì)報(bào)以下錯(cuò)誤：

輕松三步走完成Swagger的集成：安裝包->注冊(cè)組件->注冊(cè)中間件；

但是運(yùn)行起來的時(shí)候還需要手動(dòng)輸入U(xiǎn)rl地址，不太友好，希望運(yùn)行起來就直接是Swagger的頁(yè)面，如下優(yōu)化一下代碼：

這樣就完事了嗎？?當(dāng)然沒有，這樣前端同事還得時(shí)刻找你問：我要用哪個(gè)接口？接口參數(shù)的字段都是啥意思？因?yàn)榻涌诹斜黼m然展示出來了，但是不知道接口功能，傳入的條件參數(shù)字段分別代表什么意思。

來，加個(gè)注釋解決煩惱：

新加的用戶接口已經(jīng)自動(dòng)列出來了，但是我們?cè)诖a中已經(jīng)注釋，Swagger界面還是沒有顯示，那是因?yàn)檫€沒有指定Swagger的注釋來源呢。這里先注意一個(gè)問題，如果Action不顯示指定HttpMethod(如：HttpGet、HttpPost等)，Swagger會(huì)報(bào)錯(cuò)，如下：

來，我們的注釋還沒顯示出來呢，繼續(xù)往下看看↓↓↓

先針對(duì)API項(xiàng)目和Model項(xiàng)目配置生成項(xiàng)目對(duì)應(yīng)的xml文件；

增加代碼，分別指定配置文件解析注釋，然后運(yùn)行演示；

這樣就已經(jīng)完成在Swagger在線文檔中添加文字說明了，解決前后端對(duì)接的麻煩事。但是在編譯運(yùn)行的時(shí)候，會(huì)出現(xiàn)很多警告，提示沒有注釋(CS1591)：

這是因?yàn)樯蓌ml文件要求都需要注釋導(dǎo)致，作為程序員的潔癖，當(dāng)然不允許這種情況發(fā)生，小紅框標(biāo)識(shí)提示代碼為1591，我們?cè)陧?xiàng)目右鍵->屬性->生成界面中增加該代碼即可，如下：

再編譯運(yùn)行一下，是不是警告沒了，整潔就是舒服~~~~~

這里有個(gè)小細(xì)節(jié)，在配置xml讀取注釋時(shí)，如果不使用第二個(gè)參數(shù)，默認(rèn)控制器的注釋是不管用的，這里就不運(yùn)行演示了，代碼說明如下：

Swagger的集成使用差不多了，后續(xù)會(huì)在認(rèn)證的時(shí)候做擴(kuò)展。

對(duì)于Swagger的頁(yè)面，開發(fā)已經(jīng)是絕對(duì)能滿足了，但總有一些審美比較嚴(yán)格，或是有一些頁(yè)面定制化的需求，所以自定義頁(yè)面就避免不了；小伙伴會(huì)發(fā)現(xiàn)，項(xiàng)目中只是安裝了Swagger的包，沒有對(duì)應(yīng)的靜態(tài)文件，那是怎么訪問的呢？嗖的一下，靈光一閃，小伙伴一定想到之前文件系統(tǒng)中說到的嵌入文件(編譯到程序集中的文件)，默認(rèn)情況下，Swagger的相關(guān)文件都是嵌入文件，所以在項(xiàng)目中看不到。自定義頁(yè)面有三種方式：

• Swagger的頁(yè)面是前后端分離的，可直接下載下來擴(kuò)展；
  

• 直接寫一個(gè)主頁(yè)頁(yè)面，然后注入相關(guān)JS，最后將其改為嵌入文件，顯示指定加載頁(yè)面；
  

• 通過Swagger默認(rèn)提供的API，注入相關(guān)的Js文件進(jìn)行頁(yè)面自定義；

相對(duì)來說，第一種比較清晰，而且代碼與后端代碼沒有啥關(guān)系，所以這里就以第一種為例進(jìn)行演示，其余兩種留給小伙伴探索探索。

大概步驟：

先下載Swagger前后端項(xiàng)目文件(下載地址:https://github.com/swagger-api/swagger-ui/)；

將下載下來的dist中文件拷貝到WebApi中的wwwroot目錄；

WebApi開啟靜態(tài)文件處理能力，即注冊(cè)靜態(tài)文件中間件；

修改靜態(tài)文件(文件在本地，想怎么搞就怎么搞)；

運(yùn)行看效果：

這里只是提供思路，樣式不好看別說我(小伙伴不會(huì)說，對(duì)不對(duì))，美化只是時(shí)間問題嘛，自定義界面就是這么簡(jiǎn)單。

補(bǔ)充兩個(gè)小技巧：

• 通常有一些接口已經(jīng)過時(shí)，但有不能馬上廢棄，可以給一個(gè)提示；加[Obsolete]特性代表其已經(jīng)廢棄，但還可以用，有一個(gè)替換的過渡期。
  

• 有時(shí)候有些接口不想顯示在Swagger文檔中，可以加[ApiExplorerSettings(IgnoreApi = true)]

總結(jié)

看到這篇小伙伴可能會(huì)好奇，這么簡(jiǎn)單的集成，為什么要長(zhǎng)篇大論的說那么多。其實(shí)我是站在我之前學(xué)習(xí)的角度，想讓每個(gè)用法都清楚的表達(dá)出來，在使用的時(shí)候也知道為什么會(huì)這樣，所以后續(xù)的文章會(huì)循序漸進(jìn)，不會(huì)一下跳到Docker部署，網(wǎng)關(guān)使用之類的主題，如果沒有學(xué)過Docker，看著文檔也很懵，就算照著案例做出來，收獲也不是很大；別急，該說的都會(huì)一一到來，同時(shí)我也會(huì)不斷學(xué)習(xí)，爭(zhēng)取分享更多技術(shù)知識(shí)。下一節(jié)說說Jwt認(rèn)證集成使用。

一個(gè)被程序搞丑的帥小伙，關(guān)注"Code綜藝圈"，識(shí)別關(guān)注跟我一起學(xué)~~~

擼文不易，莫要白瞟，三連走起~~~~

總結(jié)

以上是生活随笔為你收集整理的跟我一起学.NetCore之Swagger让前后端不再烦恼及界面自定义的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。