NETCORE WEBAPI 搭建在線接口文檔Swagger

前後分離的好處，就是後端埋頭做業務邏輯功能，不需要過多考慮用戶體驗，只專注於數據、性能開發，對於前端需要的數據可以通過組Json或者其他方式回調，但是前後兩端需要確定好接口Api的規範，並且前端如果需要查看接口的相關信息，就需要文檔的支撐了。那麼問題來了，後端在開發過程中每次改動接口，都需要改動文檔，累不累。

Swagger

Swagger作爲一個在線文檔，通過後端的接口控制器生成一套Json串數據，實時展示後端的接口請求地址，參數，類型以及回調，很好的解決這個問題（後端可以給前端一個Swagger的地址，然後來句你自己看吧，當然還是需要多溝通的），這個在Java裏用過之後，就馬上看看有沒有.net的版本，果然，語言都是相通的，廢話不多說，開始第三方類庫的引用。

 

由於本次使用的是當前最新的版本 5.4.1  ，相關項目源碼在 github 上可以下載，且具體使用方法在下方的 README中有詳細介紹：（網上很多資料介紹都是老版本的使用，在方法上有所不同，我這裏也浪費了很多時間去查找）
項目地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

 

NuGet引用第三方類庫

工具->NuGet包管理器->管理解決方案的NuGet程序包...
在瀏覽中查找"Swashbuckle.AspNetCore"，選擇項目工程，點擊安裝。

 

引入完成後，在Startup.cs文件ConfigureServices中，加入以下代碼：

 public void ConfigureServices(IServiceCollection services)
 {
      services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

      #region Swagger
      services.AddSwaggerGen(options =>
      {
          options.SwaggerDoc("v1", new OpenApiInfo { Title = "Core WebAPI", Version = "v1" });
      }
      #endregion 
 }

在Startup.cs類裏編輯Configure方法，加入以下代碼：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
     #region Swagger
     app.UseSwagger();
     app.UseSwaggerUI(options =>
     {
         options.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
     });
     #endregion

     if (env.IsDevelopment())
     {
         app.UseDeveloperExceptionPage();
     }

     app.UseMvc();
}

重新生成工程後，訪問你的端口/swagger就可以看到接口文檔幫助界面了。

別急，還有

在線的接口文檔是有了，可一個接口啥意思都不知道，前端還是得一臉懵逼問你，這個接口啥意思啊，這個參數啥意思啊什麼的。

沒錯，註釋

還是在Startup.cs文件ConfigureServices中，加入以下代碼：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    #region Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "Core WebAPI", Version = "v1" });

        #region (可選項) 爲 Swagger JSON and UI設置xml文檔註釋路徑
        var basePath = Path.GetDirectoryName(AppContext.BaseDirectory);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議採用此方法獲取路徑）
        var xmlPath = Path.Combine(basePath, "Core_WebAPI.xml");
        options.IncludeXmlComments(xmlPath);
        #endregion
    });
    #endregion 

}

右鍵WebApi這個項目工程，點擊屬性，在生成這一欄

重新生成後會在對應目錄看到有Core_WebAPI.xml文檔文件，運行之後查看/Swagger