asp.net core 中使用 Swashbuckle.AspNetCore 生成接口文档
Swashbuckle.AspNetCore:swagger 的 asp.net core 实现
项目地址: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
仔细看了下 readme, 发现在百度找半天的东西其实 readme 里面就有...
开局一张图,然后开始编,一些基本的 asp.net core 东西就不再赘述,本文只对
Swashbuckle.AspNetCore
的几个使用要点进行描述.
如上图所示,包含功能如下(完整示例见文末)
基础使用, 添加 controler 的说明 (IDocumentFilter)
汉化操作按钮
添加通用参数 (header)- 实现 IOperationFilter
多版本控制 (暂时见 demo)
使用 JWT 的简单接口验证 (暂时见 demo)
构建一个 webapi 项目并使用 swagger
新建 asp.net core webapi 项目 dotnet new webapi
安装 nuget 包: Swashbuckle.AspNetCore , 本文使用版本 1.1.0,.net core 版本 2.0+
编辑解决方案添加 (或者在 vs 中项目属性 -> 生成 ->勾选生成 xml 文档文件)如下配置片段
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<DocumentationFile>bin\Debug\netcoreapp2.0\项目名称.xml</DocumentationFile>
</PropertyGroup>
使用 Swagger 并注入汉化脚本
c.SwaggerDoc 配置接口描述信息
c.OperationFilter 可通过 IOperationFilter 接口去添加一些公共的参数
c.DocumentFilter 通过 IDocumentFilter 接口去生成控制器的标签 (描述)
注:ConfigureServices 的方法返回值修改了,为了能够正常的使用 ServiceLocator 获取服务
private const string _Project_Name = "AspNetCoreSwaggerDemo";//nameof(AspNetCoreSwaggerDemo);
public IServiceProvider ConfigureServices(IServiceCollection services)
{
services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
services.AddSingleton(new ApiTokenConfig("A3FFB16D-D2C0-4F25-BACE-1B9E5AB614A6"));
services.AddScoped<IApiTokenService, ApiTokenService>();
services.AddSwaggerGen(c =>
{
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
c.SwaggerDoc(version, new Swashbuckle.AspNetCore.Swagger.Info
{
Version = version,
Title = $"{_Project_Name} 接口文档",
Description = $"{_Project_Name} HTTP API " + version,
TermsOfService = "None"
});
});
var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = System.IO.Path.Combine(basePath, $"{_Project_Name}.xml");
c.IncludeXmlComments(xmlPath);
//添加自定义参数,可通过一些特性标记去判断是否添加
c.OperationFilter<AssignOperationVendorExtensions>();
//添加对控制器的标签(描述)
c.DocumentFilter<ApplyTagDescriptions>();
});
services.AddMvc();
return services.BuildServiceProvider();
}
使用
InjectOnCompleteJavaScript
注入 汉化 js 脚本 即可
注:我在这个汉化脚本中添加了保存和读取赋值 token / 版本的 js 代码
ApiVersions 为枚举,配置 api 版本,以期通过 CustomRoute 特性标记解决历史 api 问题.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
//ApiVersions为自定义的版本枚举
typeof(ApiVersions)
.GetEnumNames()
.OrderByDescending(e => e)
.ToList()
.ForEach(version =>
{
//版本控制
c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{_Project_Name} {version}");
});
//注入汉化脚本
c.InjectOnCompleteJavaScript($"/swagger_translator.js");
});
//通过ServiceLocator.Resolve<Service接口>()获取注入的服务
ServiceLocator.Configure(app.ApplicationServices);
app.UseStaticFiles();
app.UseMvc();
}
实现 IDocumentFilter 及 IOperationFilter
通过 IOperationFilter 接口可以添加一些公共的参数, 添加参数到 header 或者上传图片等
通过 IDocumentFilter 接口可以生成控制器的标签 (描述)
调用方式分别为:
c.OperationFilter<AssignOperationVendorExtensions>();
c.DocumentFilter<ApplyTagDescriptions>();
//添加标签
public class ApplyTagDescriptions : IDocumentFilter
{
public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Tags = new List<Tag>
{
//添加对应的控制器描述 这个是好不容易在issues里面翻到的
new Tag { Name = "Account", Description = "登录相关接口" },
new Tag { Name = "UserCenter", Description = "用户中心接}
};
}
}
//添加通用参数,若in='header'则添加到header中,默认query参数
public class AssignOperationVendorExtensions : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
operation.Parameters = operation.Parameters ?? new List<IParameter>();
//MemberAuthorizeAttribute 自定义的身份验证特性标记
var isAuthor = operation != null && context != null && context.ApiDescription.ControllerAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute)) || context.ApiDescription.ActionAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute));
if (isAuthor)
{
//in query header
operation.Parameters.Add(new NonBodyParameter() {
Name = "x-token",
In = "header", //query formData ..
Description = "身份验证票据",
Required = false,
Type = "string"
});
}
}
}
配置完成后,给 Controler,Action 添加上注释和请求类型就可以访问 / swagger 查看你的 api 文档了~
注:
action 方法或者控制器 (或者继承的) 必须有一个包含 [Route] 特性标记
action 方法必须添加请求类型
[HttpGet]/[HttpPost]/..
如何自动将 token 保存并赋值
使用 js 生成了文本框到. authorize-wrapper, 将值保存到了本地存储中, 然后会根据接口版本将版本号参数进行复制
$(function () {
//汉化
window.SwaggerTranslator.translate();
/***************下面是添加的token相关代码*******************/
window.saveToken=function() {
var test_token = $("#customtoken").val();
localStorage.setItem("test_x_token", $("#customtoken").val());
$("input[name='X-Token']").val(test_token)
}
//token保存
var test_token = localStorage.getItem("test_x_token")||"";
$(".authorize-wrapper").append("X-Token:<input type='text' id='customtoken' value='" + test_token +"' style='width:50%' /> <button onClick='saveToken()'>保存</button>")
$("input[name='X-Token']").val(test_token)
$("input[name='X-Version']").val(swaggerUi.api.info.version)
});
除了 swagger 发现还有好多东西要写,但是一篇貌似又太多了,so.. 请听下周分解吧
这篇文章是先有 demo,有需要的可以至文末下载 demo 查看,大概还有如下几个可以写的地方
JWT 的使用
自定义路由特性标记的扩展
api 版本的控制
文章完整示例
Demo 下载 Demo 仓库地址
来源: https://www.cnblogs.com/morang/p/8325729.html