asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档
asp.net core中使用Swashbuckle.AspNetCore生成接口文档
Swashbuckle.AspNetCore:swagger的asp.net core实现,本文使用版本为v1.1.0
项目地址: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)
});
如何忽略一个接口
为Controller或者Action方法上添加特性标记[ApiExplorerSettings(IgnoreApi =true)]
即可
下一篇:Swashbuckle.AspNetCore3.0的二次封装与使用
文章完整示例
注:Demo 未修改默认启动路径,故应使用 /swagger/
访问文档:,也可自行修改 /Properties/launchSettings.json
配置默认路径
asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档的更多相关文章
- ASP.NET Core 3.1使用Swagger API接口文档
Swagger是最流行的API开发工具,它遵循了OpenAPI规范,可以根据API接口自动生成在线文档,这样就可以解决文档更新不及时的问题.它可以贯穿于整个API生态,比如API的设计.编写API文档 ...
- asp.net core 使用 swagger 生成接口文档
参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...
- Asp.Net Core Web Api 使用 Swagger 生成 api 说明文档
最近使用 Asp.Net Core Web Api 开发项目服务端.Swagger 是最受欢迎的 REST APIs 文档生成工具之一,进入我的视野.以下为学习应用情况的整理. 一.Swagger 介 ...
- .net core 使用 swagger 生成接口文档
微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...
- webapi 利用webapiHelp和swagger生成接口文档
webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...
- Django使用swagger生成接口文档
参考博客:Django接入Swagger,生成Swagger接口文档-操作解析 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文 ...
- Go语言使用swagger生成接口文档
swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服 ...
- C# Swagger 生成接口文档
一直听说Swagger是做Web API文档的好工具,这次手里暂时没什么事,类体验下它的强大之处.下面是使用Swashbuckle.net 给asp.net web API添加文档的简要步骤. 参考地 ...
- WebAPI使用Swagger生成接口文档
开发工具:VS2017 版本15.7.1 新建项目,选择空模板,下面只勾选WebAPI 配置Web.config <system.webServer> 节点改为 <system.we ...
随机推荐
- ASP.NET Core 系列视频完结,新项目实战课程发布。
今天把MVC的章节完成了,给大家从头到尾做了一个登录注册的示例,带前后端Model验证,算是完整的示例.同时借助于eShopOnContainers的示例也做了一个DBContextSeed的包装器来 ...
- nginx编译参数的内容
最近公司安排我安装几台云服务器环境 采用nginx做反向代理: 查了一下官方文档,参数比较多,很多在上线后 可能才知道注意一下的. 编译安装nginx的话 需要安装一些前置组件: 1.gcc环境:用于 ...
- Nginx的 HTTP 499 状态码处理
1.前言 今天在处理一个客户问题,遇到Nginx access log中出现大量的499状态码.实际场景是:客户的域名通过cname解析到我们的Nginx反向代理集群上来,客户的Web服务是由一个负载 ...
- coursera 视频总是缓冲或者无法观看的解决办法
注意!!!该方法针对Windows用户,亲测有效. 1.用管理员权限记事本打开host文件 2.将如下内容复制到文件末尾 52.84.246.90 d3c33hcgiwev3.cloudfront.n ...
- [置顶]
xamarin android使用gps定位获取经纬度
看了文章你会得出以下几个结论 1.android定位主要有四种方式GPS,Network(wifi定位.基站定位),AGPS定位 2.绝大部分android国产手机使用network进行定位是没有作用 ...
- bzoj 4013: [HNOI2015]实验比较
Description 小D 被邀请到实验室,做一个跟图片质量评价相关的主观实验.实验用到的图片集一共有 N 张图片,编号为 1 到 N.实验分若干轮进行,在每轮实验中,小 D会被要求观看某两张随机选 ...
- Cleaner, more elegant, and harder to recognize(翻译)
Cleaner, more elegant, and harder to recognize 更整洁,更优雅,但更难识别 看来,有些人把我几个月前一篇文章的标题"Cleaner,more e ...
- Java后端程序员都做些什么?
这个问题来自于QQ网友,一句两句说不清楚,索性写个文章. 我刚开始做Web开发的时候,根本没有前端,后端之说. 原因很简单,那个时候服务器端的代码就是一切:接受浏览器的请求,实现业务逻辑,访问数据库, ...
- 如何去除本地文件与svn服务器的关联
1.每个目录逐个去删除.svn文件夹 .svn属于隐藏文件夹,可通过操纵Windows文件资源管理器使隐藏文件可视,删除该文件,即可. 2.首先建立一个新文件,文件命名为remove-svn-fold ...
- java调优(一)