ASP.NET Core 3.0 WebApi中使用Swagger生成API文檔簡介

時間  2019-12-01
標籤 asp.net asp core 3.0 webapi 使用 swagger 生成 api 文檔 簡介 欄目 ASP 简体版
原文   原文鏈接

ASP.NET Core 3.0 WebApi中使用Swagger生成API文檔簡介

當一個WebApi完成以後，書寫API文檔是一件很是頭疼的事，由於不只要寫得清楚，能讓調用接口的人看懂，又是很是耗時耗力的一件事。在以前的一篇隨筆中（https://www.cnblogs.com/taotaozhuanyong/p/11567017.html），記載.Net Framework中WebApi生成文檔的時候，經過訪問指定的路徑，就能夠獲取到Api文檔。在.NET Core中又怎麼生成API文檔呢？使用Swagger。html

爲何使用Swagger做爲REST APIs文檔成功工具呢？shell

　　一、Swagger能夠生產一個具備互動性的API控制檯，開發者能夠用來學習和嘗試API。json

　　二、Swagger能夠生產客戶端SDK代碼用於各類不一樣的平臺上的實現。api

　　三、Swagger文件能夠在許多不一樣的平臺上從代碼註釋中自動生成。app

　　四、Swagger有一個強大的社區，裏面有許多強悍的貢獻者。dom

下面介紹如何在ASP.NET Core中使用Swagger生成API說明文檔工具

.NET Core3.0已經出來了，那咱們就基於.NET Core3.0新建一個WebApi項目吧。post

這裏爲了掩飾Swagger的使用，就不建立空項目了，選擇ASP.NET Core 3.0學習

 

 

建立完成會顯示這個樣子，會給咱們默認增長一個WeatherForecastController測試

 

 

 [ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase { private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; private readonly ILogger<WeatherForecastController> _logger; public WeatherForecastController(ILogger<WeatherForecastController> logger) { _logger = logger; } [HttpGet] public IEnumerable<WeatherForecast> Get() { var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } } View Code

當咱們這個時候運行的時候，會出現404的錯誤（不知道大家有沒有遇到，反正我是遇到了），不要着急，咱們作如下修改就行。

首先在Controller中將[Route("[controller]")]====》[Route("api/WeatherForecast")]

再在launchSettings.json中作修改。

 

 這樣，咱們再訪問一下，就成功了。

 

 迴歸今天的主題。如何使用Swagger。

首先，安裝依賴包 Swashbuckle.AspNetCore，選擇最新版本的。使用Nuget或者控制檯均可以。.Net Core2.0下，這樣是沒問題的。可是在.Net Core3.0下，最好使用PowerShell進行安裝。

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc2

 

 添加並配置Swagger中間件

引入命名空間

using Swashbuckle.AspNetCore.Swagger;

在 Startup 類中，導入如下命名空間來使用 OpenApiInfo 類：

using Microsoft.OpenApi.Models;

將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：

在.Net  Core3.0以前：

//註冊Swagger生成器，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

可是在.Net Core 3.0中，要這樣寫

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
 });

一個是new Info(),一個是new OpenApiInfo()。這也是爲何最好使用Powershell去安裝引用。不然會報錯：

TypeLoadException: Could not load type 'Microsoft.AspNetCore.Mvc.MvcJsonOptions' from assembly 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'.

在Configure方法中，啓動中間件爲生成的JSON文檔和Swagger UI提供服務：

//啓用中間件服務生成Swagger做爲JSON終結點
app.UseSwagger();
//啓用中間件服務對swagger-ui，指定Swagger JSON終結點
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

啓動應用，並導航到http://localhost:<post>/swagger/v1/swagger.sjon。生成的描述終結點的文檔顯示以下：

 

 

 可在 http://localhost:<port>/swagger 找到 Swagger UI。 經過 Swagger UI 瀏覽 API文檔，以下所示。

 

 

 要在應用的根 (http://localhost:<port>/) 處提供 Swagger UI，請將 RoutePrefix 屬性設置爲空字符串：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

自定義和擴展：

Swagger提供了爲對象模型進行歸檔和自定義UI以匹配你的主題的選項。

API信息說明

傳遞給AddSwagger方法的配置操做會添加註入做者、許可證和說明信息：在.Net Core3.0是這樣寫的，與以前寫法稍微有點區別。請注意下。

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo
     {
         Version = "v1",
         Title = "Bingle API",
         Description = "一個簡單的ASP.NET Core Web API",
         TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         Contact = new OpenApiContact
         {
             Name = "bingle",
             Email = string.Empty,
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         },
         License = new OpenApiLicense
         {
             Name = "許可證",
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         }
     });
 });

訪問地址http://localhost:<port>/swagger，就看到上述添加的信息

 

 

上述完成以後，咱們發現，接口並無註釋，那麼咱們怎麼來添加註釋呢？

XML註釋

在Visual Studio中，在「解決方案資源管理器」中右鍵單擊該項目，而後選擇「編輯 <project_name>.csproj」 。手動將突出顯示的行添加到 .csproj 文件 ：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

啓用 XML 註釋，爲未記錄的公共類型和成員提供調試信息。 警告消息指示未記錄的類型和成員。 例如，如下消息指示違反警告代碼 1591：

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

要在項目範圍內取消警告，請定義要在項目文件中忽略的以分號分隔的警告代碼列表。 將警告代碼追加到 $(NoWarn); 

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

services.AddSwaggerGen修改成以下：

注意：

　　一、對於Linux或者非Windows操做系統，文件名和路徑區分大小寫。例如「MyWebApiUseSwagger.xml」文件在Windows上有效，但在CentOS上無效

　　二、獲取應用程序路徑，建議採用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

 services.AddSwaggerGen(c =>
 {
     c.SwaggerDoc("v1", new OpenApiInfo
     {
         Version = "v1",
         Title = "Bingle API",
         Description = "一個簡單的ASP.NET Core Web API",
         TermsOfService = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         Contact = new OpenApiContact
         {
             Name = "bingle",
             Email = string.Empty,
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         },
         License = new OpenApiLicense
         {
             Name = "許可證",
             Url = new Uri("https://www.cnblogs.com/taotaozhuanyong"),
         }
     });
     //爲 Swagger JSON and UI設置xml文檔註釋路徑
     var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
     var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
     c.IncludeXmlComments(xmlPath);
 });

 

通過上面的配置，接口中的方法就有註釋了：

 

 經過上面的操做就能夠總結出來，Swagger UI顯示上述註釋代碼 <summary>元素的內部文本做爲api大的註釋！固然你還能夠將 remarks 元素添加到 Get 操做方法文檔。 它能夠補充 <summary> 元素中指定的信息，並提供更可靠的 Swagger UI。 <remarks> 元素內容可包含文本、JSON 或 XML。 代碼以下：

 /// <summary>
 /// 這是一個帶參數的get請求
 /// </summary>
 /// <remarks>
 /// 例子:
 /// Get api/Values/1
 /// </remarks>
 /// <param name="id">主鍵</param>
 /// <returns>測試字符串</returns>  
 [HttpGet("{id}")]
 public ActionResult<string> Get(int id)
 {
     return $"你請求的id是{id}";
 }

能夠看到以下效果：

 

 描述響應類型

使用WebApi的開發人員最關心的問題是返回的內容，特別是響應類型和錯誤代碼。在XML註釋和數據中表示相應類型的錯誤代碼。Get 操做成功後返回HTTP 201狀態碼。發佈的請求正文爲NULL，將返回HTTP 400狀態代碼。若是Swagger UI中沒有提供合適的文檔，那麼使用者會缺乏對這些預期的結果的瞭解。

在如下的實例中，經過突出的行解決此問題：

 /// <summary>
 /// 這是一個帶參數的get請求
 /// </summary>
 /// <remarks>
 /// 例子:
 /// Get api/Values/1
 /// </remarks>
 /// <param name="id">主鍵</param>
 /// <returns>測試字符串</returns> 
 /// <response code="201">返回value字符串</response>
 /// <response code="400">若是id爲空</response>  
 // GET api/values/2
 [HttpGet("{id}")]
 [ProducesResponseType(201)]
 [ProducesResponseType(400)]
 public ActionResult<string> Get(int id)
 {
     return $"你請求的id是{id}";
 }

如下是看到的效果

 

如何使用Swagger UI進行測試？

點擊Try it out

 

 輸入參數，再點擊Excute：

 

 獲得的響應結果：

 

以上即是在.Net Core 3.0 WebApi中使用Swagger的基本介紹。以及在.Net Core3.0下如何建立WebApi，在使用Swagger在和之前有什麼區別的的介紹。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程