swagger 的使用

最近在用 .Net Core 作項目 

瞭解到swagger 是一個不錯的工具

簡單介紹一下

在使用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

• 從「管理 NuGet 程序包」對話框中：

• 右鍵單擊「解決方案資源管理器」 > 「管理 NuGet 包」中的項目

• 將「包源」設置爲「nuget.org」

• 在搜索框中輸入「Swashbuckle.AspNetCore」

• 從「瀏覽」選項卡中選擇「Swashbuckle.AspNetCore」包，而後單擊「安裝」

添加並配置 Swagger 中間件

首先引入命名空間：

using Swashbuckle.AspNetCore.Swagger;

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

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

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

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

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

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

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

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

Swagger的高級用法（自定義以及擴展）

使用Swagger爲API文檔增長說明信息

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

1.  
   //註冊Swagger生成器，定義一個和多個Swagger 文檔services.AddSwaggerGen(c =>
2.  
   {
3.  
      c.SwaggerDoc( "v1", new Info
4.  
      {
5.  
          Version = "v1",
6.  
          Title = "yilezhu's API",
7.  
          Description = "A simple example ASP.NET Core Web API",
8.  
          TermsOfService = "None",
9.  
          Contact = new Contact
10.  
           {
11.  
               Name = "依樂祝",
12.  
               Email = string.Empty,
13.  
               Url = "http://www.cnblogs.com/yilezhu/"
14.  
           },
15.  
           License = new License
16.  
           {
17.  
               Name = "許可證名字",
18.  
               Url = "http://www.cnblogs.com/yilezhu/"
19.  
           }
20.  
       });
21.  
    });

wagger UI 顯示版本的信息以下圖所示：

爲了防止博客被轉載後，不保留本文的連接，特地在此加入本文的連接：https://www.cnblogs.com/yilezhu/p/9241261.html

爲接口方法添加註釋

你們先點擊下api，展開以下圖所示，能夠沒有註釋啊，怎麼來添加註釋呢？

按照下圖所示用三個/添加文檔註釋，以下所示

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

而後運行項目，回到swaggerUI中去查看註釋是否出現了呢

仍是沒有出現，別急，往下看！

啓用XML 註釋

可以使用如下方法啓用 XML 註釋：

• 右鍵單擊「解決方案資源管理器」中的項目，而後選擇「屬性」

• 查看「生成」選項卡的「輸出」部分下的「XML 文檔文件」框

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

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

若是你有強迫症，想取消警告怎麼辦呢？能夠按照下圖所示進行取消

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

 注意：

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

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

1.  
   //註冊Swagger生成器，定義一個和多個Swagger 文檔
2.  
              services.AddSwaggerGen( c =>
3.  
              {
4.  
                  c.SwaggerDoc( "v1", new Info
5.  
                  {
6.  
                      Version = "v1",
7.  
                      Title = "yilezhu's API",
8.  
                      Description = "A simple example ASP.NET Core Web API",
9.  
                      TermsOfService = "None",
10.  
                       Contact = new Contact
11.  
                       {
12.  
                           Name = "依樂祝",
13.  
                           Email = string.Empty,
14.  
                           Url = "http://www.cnblogs.com/yilezhu/"
15.  
                       },
16.  
                       License = new License
17.  
                       {
18.  
                           Name = "許可證名字",
19.  
                           Url = "http://www.cnblogs.com/yilezhu/"
20.  
                       }
21.  
                   });                 // 爲 Swagger JSON and UI設置xml文檔註釋路徑
22.  
                    var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工做目錄影響，建議採用此方法獲取路徑）
23.  
                    var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
24.  
                   c.IncludeXmlComments(xmlPath);
25.  
               });

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

經過上面的操做能夠總結出，Swagger UI 顯示上述註釋代碼的 <summary> 元素的內部文本做爲api大的註釋！

固然你還能夠將 remarks 元素添加到 Get 操做方法文檔。 它能夠補充 <summary> 元素中指定的信息，並提供更可靠的 Swagger UI。 <remarks> 元素內容可包含文本、JSON 或 XML。 代碼以下：

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

從新生成下項目，當好到SwaggerUI看到以下所示：

描述響應類型

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

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

咱們須要在咱們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]

而後添加相應的狀態說明：

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

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

效果以下所示

使用SwaggerUI測試api接口

下面咱們經過一個小例子經過SwaggerUI調試下接口吧

1. 點擊一個須要測試的API接口，而後點擊Parameters左右邊的「Try it out 」 按鈕

2. 在出現的參數文本框中輸入參數，以下圖所示的，輸入參數2

3. 點擊執行按鈕，會出現下面所示的格式化後的Response，以下圖所示

好了，今天的在ASP.NET Core WebApi使用Swagger生成api說明文檔看這篇就夠了的教程就到這裏了。但願可以對你們學習在ASP.NET Core中使用Swagger生成api文檔有所幫助

 

轉自 https://www.cnblogs.com/yilezhu/p/9241261.html