基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言
??為什么在開發(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文档(上篇)的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 基于.NetCore3.1搭建项目系列
- 下一篇: 基于.NetCore3.1搭建项目系列