前言

??回顧上一篇文章《使用Swagger做Api文檔?》，文中介紹了在.net core 3.1中，利用Swagger輕量級框架，如何引入程序包，配置服務，注冊中間件，一步一步的實現，最終實現生產自動生產API接口說明文檔。文中結尾也留下了一個讓大家思考的問題。在這里，我們重新回顧一下這幾個問題

? 1.?已經有接口了，但如何添加注釋呢？

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

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

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

開始

?一、為接口方法添加注釋

1 .?按照下圖所示 連點三次 / 即可添加文檔注釋

??如下所示

2.啟用XML 注釋

? ?右鍵web?項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，系統會默認生成一個,如下圖所示

?3.配置服務

??在之前注冊的Swagger服務代碼中，添加以下幾行代碼，引入xml文件

整體的代碼如下：

?4.重新編譯運行

??查看效果

注意：如果需要對控制器進行注釋說明如下，可以將

? 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)]

六、忽視Swagger注釋警告

?啟用XML?注釋后會為未記錄的公共類型和成員提供調試信息。如果出現很多警告信息??例如，以下消息指示違反警告代碼?1591：

?原來是swagger把一些action?方法都通過xml文件配置了，如果你不想每一個方法都這么加注釋，可以這么配置，在當前項目進行配置，可以忽略警告，記得在后邊加上分號?;1591

常見錯誤

?在Swagger使用的時候報錯，無法看到列表，這里說下如何調試和主要問題：

1.找不到文件

請在瀏覽器?=》F12 ==》console?控制臺?==》點擊錯誤信息地址

發現是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.?關注公眾號可以獲取資料

總結

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

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