ASP.NET Core WebApi使用Swagger生成api說明文檔看這篇就夠了


引言

在使用asp.net core 進行api開發完成后,書寫api說明文檔對於程序員來說想必是件很痛苦的事情吧,但文檔又必須寫,而且文檔的格式如果沒有具體要求的話,最終完成的文檔則完全取決於開發者的心情。或者詳細點,或者簡單點。那么有沒有一種快速有效的方法來構建api說明文檔呢?答案是肯定的, Swagger就是最受歡迎的REST APIs文檔生成工具之一!

為什么使用Swagger作為REST APIs文檔生成工具

  1. Swagger 可以生成一個具有互動性的API控制台,開發者可以用來快速學習和嘗試API。
  2. Swagger 可以生成客戶端SDK代碼用於各種不同的平台上的實現。
  3. Swagger 文件可以在許多不同的平台上從代碼注釋中自動生成。
  4. Swagger 有一個強大的社區,里面有許多強悍的貢獻者。

asp.net core中如何使用Swagger生成api說明文檔呢

  1. Swashbuckle.AspNetCore 是一個開源項目,用於生成 ASP.NET Core Web API 的 Swagger 文檔。
  2. NSwag 是另一個用於將 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的開源項目。 它提供了為 API 生成 C# 和 TypeScript 客戶端代碼的方法。

下面以Swashbuckle.AspNetCore為例為大家進行展示

Swashbuckle由哪些組成部分呢?

  • Swashbuckle.AspNetCore.Swagger:將 SwaggerDocument 對象公開為 JSON 終結點的 Swagger 對象模型和中間件。
  • Swashbuckle.AspNetCore.SwaggerGen:從路由、控制器和模型直接生成 SwaggerDocument 對象的 Swagger 生成器。 它通常與 Swagger 終結點中間件結合,以自動公開 Swagger JSON。
  • Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。 它解釋 Swagger JSON 以構建描述 Web API 功能的可自定義的豐富體驗。 它包括針對公共方法的內置測試工具。

如何使用vs2017安裝Swashbuckle呢?

  • 從“程序包管理器控制台”窗口進行安裝
    • 轉到“視圖” > “其他窗口” > “程序包管理器控制台”
    • 導航到包含 TodoApi.csproj 文件的目錄
    • 請執行以下命令 ·Install-Package Swashbuckle.AspNetCore
    • 1
  • 從“管理 NuGet 程序包”對話框中:
    • 右鍵單擊“解決方案資源管理器” > “管理 NuGet 包”中的項目
    • 將“包源”設置為“nuget.org”
    • 在搜索框中輸入“Swashbuckle.AspNetCore”
    • 從“瀏覽”選項卡中選擇“Swashbuckle.AspNetCore”包,然后單擊“安裝”
    • 2

添加並配置 Swagger 中間件

首先引入命名空間:

using Swashbuckle.AspNetCore.Swagger;

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

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

在 Startup.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:<port>/swagger/v1/swagger.json。 生成的描述終結點的文檔顯示如下json格式。

1530193531880

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

1530193586713

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

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

Swagger的高級用法(自定義以及擴展)

使用Swagger為API文檔增加說明信息

在 AddSwaggerGen 方法的進行如下的配置操作會添加諸如作者、許可證和說明信息等:

//注冊Swagger生成器,定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "yilezhu's API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = "None",
        Contact = new Contact
        {
            Name = "依樂祝",
            Email = string.Empty,
            Url = "http://www.cnblogs.com/yilezhu/"
        },
        License = new License
        {
            Name = "許可證名字",
            Url = "http://www.cnblogs.com/yilezhu/"
        }
    });
});

wagger UI 顯示版本的信息如下圖所示:

1530194050313

為了防止博客被轉載后,不保留本文的鏈接,特意在此加入本文的鏈接:https://www.cnblogs.com/yilezhu/p/9241261.html

為接口方法添加注釋

大家先點擊下api,展開如下圖所示,可以沒有注釋啊,怎么來添加注釋呢?

1530194181832

按照下圖所示用三個/添加文檔注釋,如下所示

/// <summary>
/// 這是一個api方法的注釋
/// </summary>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
     return new string[] { "value1", "value2" };
}

然后運行項目,回到swaggerUI中去查看注釋是否出現了呢

1530194413243

還是沒有出現,別急,往下看!

啟用XML 注釋

可使用以下方法啟用 XML 注釋:

  • 右鍵單擊“解決方案資源管理器”中的項目,然后選擇“屬性”
  • 查看“生成”選項卡的“輸出”部分下的“XML 文檔文件”框
  • 1530194540621

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

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

如果你有強迫症,想取消警告怎么辦呢?可以按照下圖所示進行取消

1530194772758

注意上面生成的xml文檔文件的路徑,

 注意:

​ 1.對於 Linux 或非 Windows 操作系統,文件名和路徑區分大小寫。 例如,“SwaggerDemo.xml”文件在 Windows 上有效,但在 CentOS 上無效。

​ 2.獲取應用程序路徑,建議采用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

//注冊Swagger生成器,定義一個和多個Swagger 文檔
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "yilezhu's API",
                    Description = "A simple example ASP.NET Core Web API",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "依樂祝",
                        Email = string.Empty,
                        Url = "http://www.cnblogs.com/yilezhu/"
                    },
                    License = new License
                    {
                        Name = "許可證名字",
                        Url = "http://www.cnblogs.com/yilezhu/"
                    }
                });
                // 為 Swagger JSON and UI設置xml文檔注釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄(絕對,不受工作目錄影響,建議采用此方法獲取路徑)
                var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
                c.IncludeXmlComments(xmlPath);
            });

重新生成並運行項目查看一下注釋出現了沒有

1530195392840

通過上面的操作可以總結出,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}";
 }

重新生成下項目,當好到SwaggerUI看到如下所示:

1530196170696

描述響應類型

摘錄自:https://www.cnblogs.com/yanbigfeg/p/9232844.html

接口使用者最關心的就是接口的返回內容和響應類型啦。下面展示一下201和400狀態碼的一個簡單例子:

我們需要在我們的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]

然后添加相應的狀態說明: 返回value字符串 如果id為空

最終代碼應該是這個樣子:

 /// <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}";
}

效果如下所示
狀態相應效果

使用SwaggerUI測試api接口

下面我們通過一個小例子通過SwaggerUI調試下接口吧

  1. 點擊一個需要測試的API接口,然后點擊Parameters左右邊的“Try it out ” 按鈕
  2. 在出現的參數文本框中輸入參數,如下圖所示的,輸入參數2
  3. 點擊執行按鈕,會出現下面所示的格式化后的Response,如下圖所示

1530196606406

好了,今天的在ASP.NET Core WebApi使用Swagger生成api說明文檔看這篇就夠了的教程就到這里了。希望能夠對大家學習在ASP.NET Core中使用Swagger生成api文檔有所幫助!

總結

​ 本文從手工書寫api文檔的痛處說起,進而引出Swagger這款自動生成api說明文檔的工具!然后通過通俗易懂的文字結合圖片為大家演示了如何在一個ASP.NET Core WebApi中使用SwaggerUI生成api說明文檔。最后又為大家介紹了一些ASP.NET Core 中Swagger的一些高級用法!希望對大家在ASP.NET Core中使用Swagger有所幫助!


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2021 ITdaan.com