Swagger實現API文件功能

wagger也稱為open api，swagger從api文件中手動完成工作，並提供一系列用於生成，視覺化和維護api文件的解決方案。簡單的說就是一款讓你更好的書寫api文件的框架。

我們為什麼選擇swagger，現在的**開發結果越來越注重前後端的分離，比如以前的webfrom到現在的mvc模式都是為了這個前後端的分離。就算再如何的分離實現，也是不可避免的要進行資料互動的，那麼介面的重要性就提現出來了。他成了前端和後端互動的重要途徑，api文件也因此成了前端開發人員與後端開發人員的重要紐帶。所有我們有乙個api文件框架豈不是美哉。

swashbuckle有三個主要元件：

swashbuckle.aspnetcore.swagger：swagger物件模型和中介軟體，將swaggerdocument物件公開為json端點。

swashbuckle.aspnetcore.swaggergen：一種swagger生成器，可swaggerdocument直接從路由，控制器和模型構建物件。它通常與swagger端點中介軟體結合使用，以自動公開swagger json。

swashbuckle.aspnetcore.swaggerui：swagger ui工具的嵌入式版本。它將swagger json解釋為構建豐富的，可定製的web api功能描述體驗。它包括用於公共方法的內建測試線束。

首先我們要有乙個webapi專案，假設我們已經建立好了，不懂webapi如何建立的請看這篇文章：建立簡單的webapi

好了現在我們已經有了專案那我們就開始新增引用吧：

nuget 命令列：install-package swashbuckle.aspnetcore

然後配置startup.cs 檔案中的configureservices方法，當然首先不要忘記引用一下using swashbuckle.aspnetcore.swagger命名空間，不然info類會報錯。

public void configureservices(iservicecollection services)
);});
}

然後在configure方法中新增：

//允許中介軟體為json端點服務生成的siggg

//使中介軟體能夠服務於輕量級使用者介面（html、js、css等），並指定swagjer json端點

);

這樣就可以啟動了，配置好以上就是乙個最簡單的api文件示例了。首先你可以訪問：http://localhost:/swagger/v1/swagger.json 這個**看到端點生成的文件。

當然你想看到的是這個：http://localhost:/swagger ，你輸入這個**也可以，當然我把他配置成了根節點，這樣直接啟動根節點就是該頁面。主要是上面**中的： c.routeprefix = string.empty這句**。

我們可以擴充套件一些附加資訊，比如作者，許可證，服務條款等。傳遞給該addswaggergen方法的配置：

//swagger生成器新增到方法中的服務集合中
services.addswaggergen(options =>
,//許可證
license = new license
});});

顯示結果

啟用xml注釋可為未記錄的公共型別和成員提供除錯資訊。未記錄的型別和成員由警告訊息指示。配置swagger以使用生成的xml檔案。

在我們實現前先設定一下專案屬性：

這樣就可以在專案bin下生成xml檔案了。下面進行**配置啟用，還是在startup類中的configureservices方法中，在我們剛才配置的下面在增加以下**：

// 設定swager json和ui的注釋路徑。
var xmlfile = $".xml";
options.includexmlcomments(xmlpath);

使用反射主要是為了生成乙個與專案檔名相同的xml檔案。第二部然後是配置檔案路徑。這些配置好了以後。我們就可以把方法或者類的三道斜槓（「///」）的注釋新增到動作。我們來看一下效果。

介面：

注意哦，就是開啟這個功能，專案會自動檢測那些方法或者類沒有注釋，會給出警告。

當然我們也可以取消掉：我們在個人.csproj檔案中使用分號分隔來取消警告資訊：

on1701;1702;1705;1591

這樣就不會有警告提示了。

介面使用者最關心的就是介面的返回內容和相應型別啦。下面展示一下201和400乙個簡單例子：

我們需要在我們的方法上新增：[producesresponsetype(201)][producesresponsetype(400)]

然後新增相應的狀態說明：返回value字串

如果id為空

最終**應該是這個樣子：

執行起來我們看一下結果：

Swagger實現API文件功能

使用swagger生成API文件

API文件工具 Swagger的整合

Swagger 訪問頁面不能顯示API文件的問題

Swagger實現API文件功能

使用swagger生成API文件

API文件工具 Swagger的整合

Swagger 訪問頁面不能顯示API文件的問題

相關推薦