Asp.net core WebApi 使用Swagger生成幫助頁

      最近咱們團隊一直進行.net core的轉型，web開發向着先後端分離的技術架構演進，咱們後臺主要是採用了asp.net core webapi來進行開發，開始每次調試以及與前端人員的溝通上都存在這效率低下的問題，一次在看微軟asp.net core官方文檔的時候，發現了swagger這個好東西。而後在實際的項目中引入了該技術。咱們開發人員測試本身寫的api的過程大大獲得了簡化，前端人員也能夠根據咱們提供的swagger help pages 本身進行一些前端代碼的測試，大大提升了先後端的開發效率。下面我就拿我本身的真實上線項目來一步一步的講解如何在asp.net core webapi中引入swagger。(也能夠參照微軟官方文檔：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger) 

     1、引入swagger Nuget包

         右鍵點擊wepapi項目的依賴項，點擊管理Nuget程序包，以下圖：

     

在打開的NuGet包程序管理界面，輸入：Swashbuckle.AspNetCore 目前該程序包的版本爲1.0.0，點擊安裝。

安裝完後，須要在項目中的Startup.cs文件中進行配置。

   2、配置Swagger

    打開Startup.cs 文件，在ConfigureServices 方法中，添加以下代碼：

    

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "TwBusManagement接口文檔",
                    Description = "RESTful API for TwBusManagement",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Alvin_Su", Email = "asdasdasd@outlook.com", Url = "" }
                });

                //Set the comments path for the swagger json and ui.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "twbusapi.xml");
                c.IncludeXmlComments(xmlPath);

              //  c.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader參數
            });

注意上段代碼的最後三行，是咱們api描述文檔xml的生成地址和文件名，須要在項目的屬性中進行配置。以下圖：

另外上圖中，禁止顯示警告中，添加1591 代碼，能夠過濾掉一些類名沒有寫註釋的報警信息。

最後須要在Configure方法中，添加以下代碼，注意下面的代碼必須添加在  app.UseMvc() 前面：

 // Enable middleware to serve generated Swagger as a JSON endpoint.
            app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "TwBusManagement API V1");
                c.ShowRequestHeaders();
            });

以上配置完後，就可使用Swagger生成的幫助頁面了，運行項目後，在瀏覽器地址 加上後綴 /swagger就能夠跳轉到幫助頁面：

固然咱們開發人員在開發項目的過程當中並不想每次都要手動輸入地址才能跳轉到幫助頁面，這樣太麻煩。咱們可藉助visual studio 進行跳轉，以下圖：

打開 launchSettings.json 文件，把webapi項目的啓動路徑設置成 swagger。這樣每次調試運行項目都會自動跳轉到swagger幫助頁面

      3、Swagger的一些高級用法

      Swagger很是強大，不單單是一些幫助頁面信息，還能夠進行api的調試。這樣就能夠不用藉助第三方工具 如：postman，進行webapi的調試。swagger通過配置，還能夠輸入一些http頭部信息，如權限認證信息等。下面就來說解如下具體的配置。

        首先咱們須要新建一個類 HttpHeaderOperation，讓該類繼承IOperationFilter 接口，該接口需引入命名空間：Swashbuckle.AspNetCore.SwaggerGen，實現接口方法Apply 代碼以下：

     

 public class HttpHeaderOperation : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            if (operation.Parameters == null)
            {
                operation.Parameters = new List<IParameter>();
            }

            var actionAttrs = context.ApiDescription.ActionAttributes();

            var isAuthorized= actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));

            if (isAuthorized == false) //提供action都沒有權限特性標記，檢查控制器有沒有
            {
                var controllerAttrs= context.ApiDescription.ControllerAttributes();

                isAuthorized= controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
            }

            var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));

            if (isAuthorized && isAllowAnonymous == false)
            {
                operation.Parameters.Add(new NonBodyParameter()
                {
                    Name = "Authorization",  //添加Authorization頭部參數
                    In = "header",
                    Type = "string",
                    Required = false
                });
            }
        }
    }

   而後在 Startup.cs 中的 ConfigureServices 方法，找到以前的AddSwaggerGen 代碼段，在最後添加以下代碼：

c.OperationFilter<HttpHeaderOperation>()

  services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "TwBusManagement接口文檔",
                    Description = "RESTful API for TwBusManagement",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "Alvin_Su", Email = "alvin_su@outlook.com", Url = "" }
                });

                //Set the comments path for the swagger json and ui.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "twbusapi.xml");
                c.IncludeXmlComments(xmlPath);

                c.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader參數
            });

 這樣，咱們容許webapi項目後，就能夠輸入 Authorization 頭部參數了。以下圖：

   

 

        更多關於Swagger的用法能夠參考https://github.com/domaindrivendev/Swashbuckle.AspNetCore 以及微軟文檔：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger