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的使用了
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
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 = "桂素伟" ,
},
});
//设置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
1
2
3
4
|
.logo__title { font-weight : bold ;
font-size : 0.8em ;
} |
custom.js
1
2
|
var titles=document.getElementsByClassName( "logo__title" );
titles[0].innerHTML = "Swagger测试" ;
|
关于美化UI可以运行,查看具体的html Elements,然后去写css或js
代码参考:https://github.com/axzxs2001/Asp.NetCoreExperiment
本文转自桂素伟51CTO博客,原文链接:http://blog.51cto.com/axzxs/1903143 ,如需转载请自行联系原作者