Swagger是一个把api和注释生成一个可视(或可访问)的输出工具,关且还可以进行手工测试我们的api,解决了程序不想写文档的问题(哈哈)。

 

Swashbuckle.AspNetCore是用来解决asp.net core下的api文档,不但能称显UI,还可以在UI上进行测试。

如果在asp.net core中使用swagger,首先在nuget下安装Swashbuckle.AspNetCore,不过现在是预览版,一定要把“包括预发行版”打上勾。

wKioL1i6H5nhOmrtAAGsbe-7LLw806.png-wh_50

同时还要添加三个引用:

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 = "axzxs2001@163.com"
             },
         });
         //设置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

wKioL1i6H-eSQ63pAAOSWEIb8yg179.png-wh_50


代码参考:https://github.com/axzxs2001/Asp.NetCoreExperiment