Swagger 在asp.net core中的應用2

Swagger是一個把api和註釋生成一個可視（或可訪問）的輸出工具，關且還可以進行手工測試我們的api，解決了程序不想寫文檔的問題（哈哈）。

 

Swashbuckle.AspNetCore是用來解決asp.net core下的api文檔，不但能稱顯UI，還可以在UI上進行測試。

如果在asp.net core中使用swagger，首先在nuget下安裝Swashbuckle.AspNetCore，不過現在是預覽版，一定要把“包括預發行版”打上勾。

同時還要添加三個引用：

Swashbuckle.AspNetCore.SwaggerGen是生成Swagger文檔的組件

Swashbuckle.AspNetCore.Swagger：是把Swagger文檔生成Json Api的組件

Swashbuckle.AspNetCore.SwaggerUI，是把Json Api轉成頁面的組件

 

接下來設置項目屬性，生成-Output節點的XML documentation file打上勾，用來保證能把action上的註釋生成xml文檔。

同時，Controller中的action都要加http特性，這樣方例生成swagger文檔時能找到準確的api，這點很重要

接下來，就要在Starup中去調置Swagger的使用了

public void ConfigureServices(IServiceCollection services)
 {           
     services.AddMvc();
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new Info
         {
             Title = "Swagger測試",
             Version = "v1",
             Description = "Swagger測試RESTful API ",
             TermsOfService = "None",
             Contact = new Contact
             {
                 Name = "桂素偉",
                 Email = "[email protected]"
             },
         });
         //設置xml註釋文檔，注意名稱一定要與項目名稱相同
         var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "SwaggerDemo.xml");
         c.IncludeXmlComments(filePath);
         //處理複雜名稱
         c.CustomSchemaIds((type) => type.FullName);
     });
 }
      
 public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
 {
     loggerFactory.AddConsole(Configuration.GetSection("Logging"));
     loggerFactory.AddDebug();
     app.UseMvc();
     app.UseSwagger(c =>
     {
         //設置json路徑
         c.RouteTemplate = "docs/{documentName}/swagger.json";
     });
     app.UseSwaggerUI(c =>
     {
         //訪問swagger UI的路由，如http://localhost:端口/docs
         c.RoutePrefix = "docs";
         c.SwaggerEndpoint("/docs/v1/swagger.json", "Swagger測試V1");
         //更改UI樣式
         c.InjectStylesheet("/swagger-ui/custom.css");
         //引入UI變更js
         c.InjectOnCompleteJavaScript("/swagger-ui/custom.js");
     });
 }

關於更多的UseSwagger參數和UseSwaggerUI參數可參考

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

 

設置中的custom.css和custom.js如下

custom.css

.logo__title {
 font-weight:bold;
 font-size:0.8em;
}

custom.js

var titles=document.getElementsByClassName("logo__title");
titles[0].innerHTML = "Swagger測試";

關於美化UI可以運行，查看具體的html Elements，然後去寫css或js

代碼參考：https://github.com/axzxs2001/Asp.NetCoreExperiment