前言

??為什么在開發(fā)中，接口文檔越來越成為前后端開發(fā)人員溝通的樞紐呢？

??隨著業(yè)務的發(fā)張，項目越來越多，而對于支撐整個項目架構體系而言，我們對系統(tǒng)業(yè)務的水平拆分，垂直分層，讓業(yè)務系統(tǒng)更加清晰，從而產生一系統(tǒng)平臺和系統(tǒng)，并使用接口進行數(shù)據(jù)交互。因此可見，業(yè)務的不斷發(fā)展，接口不斷增多，很多接口各自寄宿在不同的項目中，如果沒有使用api工具進行管理，那么使用和說明將變得非常復雜。所以，接口管理運營應運而生。

??在過去的開發(fā)中，沒有API文檔管理工具之前，很多的API文檔在什么地方寫的都有，有在word寫的，有在excel寫的，也有對應的項目目錄下readme.md寫的，每個公司都有每個公司的玩法，但是文檔規(guī)范極其不統(tǒng)一，甚至出現(xiàn)開發(fā)接口更新，但文檔不更新，最終導致代碼和接口不匹配，開發(fā)功能出問題。擼碼一分鐘，對接三小時。這往往是大家最痛苦的。? ??

? ? ?

??因此，在前后端分離的情況下，怎樣讓前后端開發(fā)人員更容易、更直觀、更舒服的方式進行溝通交流。在這里，推薦一款輕量級的項目框架Swagger給大家使用。Swagger就是一款讓你更好書寫API文檔的框架

開始

一、 引用Swagger的nuget包

??Swashbuckle.AspNetCore

?然后就在項目的Nuget依賴里看到剛剛引入的Swagger

二、服務配置環(huán)節(jié)

在Startup.cs頁面中：

編輯?ConfigureServices類：

其中的Url地址不能為空。

三、中間件啟動環(huán)節(jié)

編輯Configure類

注意：路徑配置，設置為空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉，如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix ="doc";

到這里之后，我們已經(jīng)完成了對swagger的添加，F5運行之后，

?運行項目之后，我們發(fā)現(xiàn)官方默認的是?/WeatherForecast地址，所以我們修改成在域名后面輸入/index.html，就可以正常訪問了。

如果想修改默認的啟動地址，可以在launchSetting.json文件中的launchUrl設置為空，或者刪除掉就可以了。

?這個時候我們再次啟動項目，就可以直接訪問根目錄下的文件了。

如果啟動應用，并導航到?http://localhost:<port>/swagger/V1/swagger.json。生成的描述終結點的文檔顯示如下json格式。

補充

? 1.?已經(jīng)有接口了，但如何添加注釋呢？

? 2.?作為接口使用者，我們關心的是接口的返回內容和響應類型，那我們如何定義描述響應類型呢？

? 3.?在項目開發(fā)中，使用的實體類，又如何在Swagger中展示呢？

? 4.?在部署項目，引用Swagger既有文檔又不需要額外部署，但是如何在開發(fā)環(huán)境中使用，而在生產環(huán)境中禁用呢？

?

以上的這些內容，會在下一篇講解Swagger做Api文檔做詳解。

好了，今天的使用Swagger做Api文檔上篇內容就說到這里了，希望能給大家在使用Core開發(fā)項目中使用Swagger生產接口文檔帶來幫助。

總結

?1.?從過去手寫Api文檔，到引入Swagger工具自動生產API接口說明文檔，這一轉換，讓更多的接口可以以通俗易懂的方式展現(xiàn)給開發(fā)人員。

?2.?后續(xù)會繼續(xù)介紹Swagger的一些高級用法，希望對大家使用Swagger有所幫助。

總結

以上是生活随笔為你收集整理的基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)的全部內容，希望文章能夠幫你解決所遇到的問題。

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