ASP.NET Core WebApi使用Swagger生成api說明文檔

1. Swagger是什麼？

    Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

 

2.Swagger能夠幹什麼？

a.接口，服務可視化，很是清晰，好用

b.作接口測試，方便測試人員使用

Github：https://github.com/wuyabusi/swagger.git

第一步：建立WebApi工程

第二步：引入swagger的包

第三步：打開解決方案屬性-->生成，勾選XML文檔文件，保存

第四步：在Startup.cs的ConfigureServices方法中添加配置

   public void ConfigureServices(IServiceCollection services)
        {
            //配置跨域處理
            services.AddCors(options =>
            {
                options.AddPolicy("any", builder =>
                {
                    builder.AllowAnyOrigin() //容許任何來源的主機訪問
                    .AllowAnyMethod()
                    .AllowAnyHeader()
                    .AllowCredentials();//指定處理cookie
                });
            });
            //配置Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "接口文檔",
                    Description = "RESTful API for TwBusManagement"
                });
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "TextApi.xml");//和上面圖片中xml地址相同
                c.IncludeXmlComments(xmlPath);
                //
            });

            services.AddMvc();
        }

第五步.在Startup.cs的Configure方法中添加配置, 啓用中間件爲生成的 JSON 文檔和 Swagger UI 提供服務：

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseStaticFiles(); //靜態文件服務
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "TwBusManagement API V1");
                //c.ShowExtensions();
            });
            app.UseMvc();
        }

第六步.在Properties下的launchSettings.json的文件中修改初始頁面

而後運行就能夠

若有問題，歡迎指正

點擊應用下面的鏈接,能夠導航到 http://localhost:<port>/swagger/v1/swagger.json生成的描述終結點的文檔顯示以下json格式。

 

參考出處:https://www.cnblogs.com/wuyabaibsd/p/9413994.html

=================================================================================================

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 顯示版本的信息以下圖所示：

爲了防止博客被轉載後，不保留本文的連接，特地在此加入本文的連接：http://www.javashuo.com/article/p-xlcnpzoq-gy.html

爲接口方法添加註釋

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

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

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

而後運行項目，回到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這樣來獲取

//註冊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);
            });

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

經過上面的操做能夠總結出，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看到以下所示：

描述響應類型

摘錄自：http://www.javashuo.com/article/p-qbylylet-ha.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，以下圖所示

好了，今天的在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有所幫助！

 

參考出處:http://www.cnblogs.com/yilezhu/p/9241261.html

 

後續會更新生成客戶端代碼的使用和說明.