前言 回顧上一篇文章《使用Swagger做Api文檔 》，文中介紹了在.net core 3.1中，利用Swagger輕量級框架，如何引入程序包，配置服務(wù)，注冊中間件，一步一步的實現(xiàn)，最終實現(xiàn)生產(chǎn)自動生產(chǎn)API接口說明文檔。文中結(jié)尾也留下了一個讓大家思考的問題。在這里，我們重新回顧一下這幾個問題 1. 已經(jīng)有接口了，但如何添加注釋呢？ 2. 作為接口使用者，我們關(guān)心的是接口的返回內(nèi)容和響應(yīng)類型，那我們?nèi)绾味x描述響應(yīng)類型呢？ 3. 在項目開發(fā)中，使用的實體類，又如何在Swagger中展示呢？ 4. 在部署項目，引用Swagger既有文檔又不需要額外部署，但是如何在開發(fā)環(huán)境中使用，而在生產(chǎn)環(huán)境中禁用呢？ 開始一、為接口方法添加注釋1 . 按照下圖所示 連點三次 / 即可添加文檔注釋如下所示
2.啟用XML 注釋右鍵web 項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，系統(tǒng)會默認生成一個,如下圖所示
3.配置服務(wù)在之前注冊的Swagger服務(wù)代碼中，添加以下幾行代碼，引入xml文件 var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應(yīng)用程序所在目錄（絕對，不受工作目錄影響，建議采用此方法獲取路徑） //var basePath = AppContext.BaseDirectory;var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//這個就是剛剛配置的xml文件名 // c.IncludeXmlComments(xmlPath);//默認的第二個參數(shù)是false,對方法的注釋 c.IncludeXmlComments(xmlPath,true); // 這個是controller的注釋 整體的代碼如下： public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>{
c.SwaggerDoc("V1", new OpenApiInfo
{
Version = "V1", //版本 Title = $"XUnit.Core 接口文檔-NetCore3.1", //標(biāo)題Description = $"XUnit.Core Http API v1", //描述Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },
License = new OpenApiLicense { Name = "艾三元許可證", Url = new Uri("http://i3yuan.cnblogs.com") }
});var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應(yīng)用程序所在目錄（絕對，不受工作目錄影響，建議采用此方法獲取路徑） //var basePath = AppContext.BaseDirectory;var xmlPath = Path.Combine(basePath, "XUnit.Core.xml");//這個就是剛剛配置的xml文件名c.IncludeXmlComments(xmlPath);//默認的第二個參數(shù)是false,對方法的注釋// c.IncludeXmlComments(xmlPath,true); //這個是controller的注釋 });
services.AddControllers();
}4.重新編譯運行查看效果
注意：如果需要對控制器進行注釋說明如下，可以將 c.IncludeXmlComments(xmlPath,true); 這個設(shè)置為true,顯示效果如下：
二、描述響應(yīng)類型接口使用者最關(guān)心的就是接口的返回內(nèi)容和相應(yīng)類型啦。下面展示一下201和400一個簡單例子： 我們需要在我們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)] 然后添加相應(yīng)的狀態(tài)說明：<response code="201">返回value字符串</response><response code="400">如果id為空</response> 最終代碼應(yīng)該是這個樣子： /// <summary>/// values帶id參數(shù)的get/// </summary>/// <param name="id"></param>/// <response code="201">返回value字符串</response>/// <response code="400">如果id為空</response> /// <returns></returns>[HttpGet("{id}")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]public string Get(int id)
{return "value";
}效果如下：
三、實體類展示添加注釋新建一個Movie的實體類，MovieModel /// <summary>/// 這是電影實體類/// </summary>public class MovieModel
{/// <summary>/// Id/// </summary>public int Id { get; set; }/// <summary>/// 影片名稱/// </summary>public string Name { get; set; }/// <summary>/// 類型/// </summary>public string Type { get; set; }
}在控制器中引入接口方法 /// <summary>/// post方式提交電影名稱/// </summary>/// <param name="movie"></param> [HttpPost]public async Task<string> Post(MovieModel movie)
{return movie.Name;
}效果如下：
四、在生產(chǎn)環(huán)境中禁用可以將Swagger的UI頁面配置在Configure的開發(fā)環(huán)境之中 放到if(env.IsDevelopment())即可。 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();#region Swagger 只在開發(fā)環(huán)節(jié)中使用app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");
c.RoutePrefix = string.Empty; //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的 //路徑配置，設(shè)置為空，表示直接在根域名（localhost:8001）訪問該文件 // c.RoutePrefix = "swagger"; // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html });#endregion}
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>{
endpoints.MapControllers();
});
}五、隱藏某些接口如果不想顯示某些接口，直接在controller 上，或者action 上，增加特性 [ApiExplorerSettings(IgnoreApi = true)]
六、忽視Swagger注釋警告啟用 XML 注釋后會為未記錄的公共類型和成員提供調(diào)試信息。如果出現(xiàn)很多警告信息 例如，以下消息指示違反警告代碼 1591：
原來是swagger把一些 action 方法都通過xml文件配置了，如果你不想每一個方法都這么加注釋，可以這么配置，在當(dāng)前項目進行配置，可以忽略警告，記得在后邊加上分號 ;1591
常見錯誤在Swagger使用的時候報錯，無法看到列表，這里說下如何調(diào)試和主要問題： 1.找不到文件
請在瀏覽器 =》 F12 ==》 console 控制臺 ==》點擊錯誤信息地址 發(fā)現(xiàn) 是404 ，說明是找不到指定的文件，可以存在以下情況： 這是因為接口json文檔定義和調(diào)用不是一個 1、定義： ConfigureServices 方法中的 services.AddSwaggerGen 注冊的一個名字 c.SwaggerDoc("v1", 2、調(diào)用： Configure 方法中的 app.UseSwaggerUI(c => 調(diào)用 c.SwaggerEndpoint("/swagger/V1/swagger.json； 看看兩者是否一致
2. 500錯誤無法解析
直接鏈接http://localhost:xxxxx/swagger/v1/swagger.json，就能看到錯誤了
這種可以存在以下情況： 1 . 接口請求的方式不明確： 少了[httpget]、[httpPost] 等，導(dǎo)致無法解析
總結(jié)1. 通過這一篇的整體學(xué)習(xí)，我們已經(jīng)解決了上一篇文章留下的問題，也知道了怎樣更好的使用Swagger進行開發(fā)接口文檔，更加方便快捷的使用 2. 從上篇的引用配置啟動，到這一篇的升級改造，讓接口文檔更加通俗易懂。 |
|
|
