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

這篇文章將為大家詳細講解有關(guān)Asp.net core WebApi如何使用Swagger生成幫助頁，小編覺得挺實用的，因此分享給大家做個參考，希望大家閱讀完這篇文章后可以有所收獲。

 一、引入swagger Nuget包

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

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

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

二、配置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參數(shù)
      });

注意上段代碼的最后三行，是我們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就可以跳轉(zhuǎn)到幫助頁面：

當然我們開發(fā)人員在開發(fā)項目的過程中并不想每次都要手動輸入地址才能跳轉(zhuǎn)到幫助頁面，這樣太麻煩。我們可借助visual studio 進行跳轉(zhuǎn)，如下圖：

打開 launchSettings.json 文件，把webapi項目的啟動路徑設(shè)置成 swagger。這樣每次調(diào)試運行項目都會自動跳轉(zhuǎn)到swagger幫助頁面

三、Swagger的一些高級用法

Swagger非常強大，不僅僅是一些幫助頁面信息，還可以進行api的調(diào)試。這樣就可以不用借助第三方工具 如：postman，進行webapi的調(diào)試。swagger經(jīng)過配置，還可以輸入一些http頭部信息，如權(quán)限認證信息等。下面就來講解以下具體的配置。

首先我們需要新建一個類 HttpHeaderOperation，讓該類繼承IOperationFilter 接口，該接口需引入命名空間：Swashbuckle.AspNetCore.SwaggerGen，實現(xiàn)接口方法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都沒有權(quán)限特性標記，檢查控制器有沒有
      {
        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頭部參數(shù)
          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參數(shù)
      });

這樣，我們允許webapi項目后，就可以輸入 Authorization 頭部參數(shù)了。如下圖：

關(guān)于“Asp.net core WebApi如何使用Swagger生成幫助頁”這篇文章就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，使各位可以學到更多知識，如果覺得文章不錯，請把它分享出去讓更多的人看到。