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