實時航班追蹤背后的技術：在線飛機追蹤器的工作原理
隨著業務的發張，項目越來越多，而對于支撐整個項目架構體系而言，我們對系統業務的水平拆分，垂直分層，讓業務系統更加清晰，從而產生一系統平臺和系統，并使用接口進行數據交互。因此可見，業務的不斷發展，接口不斷增多，很多接口各自寄宿在不同的項目中，如果沒有使用api工具進行管理，那么使用和說明將變得非常復雜。所以，接口管理運營應運而生。
在過去的開發中，沒有API文檔管理工具之前，很多的API文檔在什么地方寫的都有，有在word寫的，有在excel寫的，也有對應的項目目錄下readme.md寫的，每個公司都有每個公司的玩法，但是文檔規范極其不統一，甚至出現開發接口更新，但文檔不更新，最終導致代碼和接口不匹配，開發功能出問題。擼碼一分鐘，對接三小時。這往往是大家最痛苦的。
因此，在前后端分離的情況下，怎樣讓前后端開發人員更容易、更直觀、更舒服的方式進行溝通交流。在這里，推薦一款輕量級的項目框架Swagger給大家使用。Swagger就是一款讓你更好書寫API文檔的框架
Swashbuckle.AspNetCore
然后就在項目的Nuget依賴里看到剛剛引入的Swagger
在Startup.cs頁面中：
編輯 ConfigureServices類：
其中的Url地址不能為空。
編輯Configure類
注意：路徑配置，設置為空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉，如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix =”doc”;
到這里之后，我們已經完成了對swagger的添加，F5運行之后，
運行項目之后，我們發現官方默認的是 /WeatherForecast地址，所以我們修改成在域名后面輸入/index.html，就可以正常訪問了。
如果想修改默認的啟動地址，可以在launchSetting.json文件中的launchUrl設置為空，或者刪除掉就可以了。
這個時候我們再次啟動項目，就可以直接訪問根目錄下的文件了。
如果啟動應用，并導航到 http://localhost:<port>/swagger/V1/swagger.json。生成的描述終結點的文檔顯示如下json格式。
1. 已經有接口了，但如何添加注釋呢？
2. 作為接口使用者，我們關心的是接口的返回內容和響應類型，那我們如何定義描述響應類型呢？
3. 在項目開發中，使用的實體類，又如何在Swagger中展示呢？
4. 在部署項目，引用Swagger既有文檔又不需要額外部署，但是如何在開發環境中使用，而在生產環境中禁用呢？
以上的這些內容，會在下一篇講解Swagger做Api文檔做詳解。
好了，今天的使用Swagger做Api文檔上篇內容就說到這里了，希望能給大家在使用Core開發項目中使用Swagger生產接口文檔帶來幫助。
1. 從過去手寫Api文檔，到引入Swagger工具自動生產API接口說明文檔，這一轉換，讓更多的接口可以以通俗易懂的方式展現給開發人員。
2. 后續會繼續介紹Swagger的一些高級用法，希望對大家使用Swagger有所幫助。
回顧上一篇文章《使用Swagger做Api文檔 》，文中介紹了在.net core 3.1中，利用Swagger輕量級框架，如何引入程序包，配置服務，注冊中間件，一步一步的實現，最終實現生產自動生產API接口說明文檔。文中結尾也留下了一個讓大家思考的問題。在這里，我們重新回顧一下這幾個問題
1. 已經有接口了，但如何添加注釋呢？
2. 作為接口使用者，我們關心的是接口的返回內容和響應類型，那我們如何定義描述響應類型呢？
3. 在項目開發中，使用的實體類，又如何在Swagger中展示呢？
4. 在部署項目，引用Swagger既有文檔又不需要額外部署，但是如何在開發環境中使用，而在生產環境中禁用呢？
如下所示
右鍵web 項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，系統會默認生成一個,如下圖所示
在之前注冊的Swagger服務代碼中，添加以下幾行代碼，引入xml文件
整體的代碼如下：
查看效果
注意：如果需要對控制器進行注釋說明如下，可以將 c.IncludeXmlComments(xmlPath,true); 這個設置為true,顯示效果如下：
接口使用者最關心的就是接口的返回內容和相應類型啦。下面展示一下201和400一個簡單例子：
我們需要在我們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相應的狀態說明：<response code=”201″>返回value字符串</response><responsecode=”400″>如果id為空</response>
最終代碼應該是這個樣子：
效果如下：
新建一個Movie的實體類，MovieModel
在控制器中引入接口方法
效果如下：
可以將Swagger的UI頁面配置在Configure的開發環境之中
放到if(env.IsDevelopment())即可。
如果不想顯示某些接口，直接在controller 上，或者action 上，增加特性
[ApiExplorerSettings(IgnoreApi = true)]
啟用XML 注釋后會為未記錄的公共類型和成員提供調試信息。如果出現很多警告信息 例如，以下消息指示違反警告代碼 1591：
原來是swagger把一些action 方法都通過xml文件配置了，如果你不想每一個方法都這么加注釋，可以這么配置，在當前項目進行配置，可以忽略警告，記得在后邊加上分號 ;1591
在Swagger使用的時候報錯，無法看到列表，這里說下如何調試和主要問題：
1.找不到文件
發現是404，說明是找不到指定的文件，可以存在以下情況：
這是因為接口json文檔定義和調用不是一個
1、定義：
ConfigureServices方法中的 services.AddSwaggerGen 注冊的一個名字 c.SwaggerDoc(“v1”,
2、調用：
Configure 方法中的 app.UseSwaggerUI(c => 調用 c.SwaggerEndpoint(“/swagger/V1/swagger.json；
看看兩者是否一致
2. 500錯誤無法解析
直接鏈接http://localhost:xxxxx/swagger/v1/swagger.json，就能看到錯誤了
這種可以存在以下情況：
1 . 接口請求的方式不明確：少了[httpget]、[httpPost]等，導致無法解析
1. 通過這一篇的整體學習，我們已經解決了上一篇文章留下的問題，也知道了怎樣更好的使用Swagger進行開發接口文檔，更加方便快捷的使用
2. 從上篇的引用配置啟動，到這一篇的升級改造，讓接口文檔更加通俗易懂。
3. 關注公眾號可以獲取資料
文章轉自微信公眾號@元說技術
