欢迎来到汇淘网

汇淘网

asp.net core web api 生成 swagger 文档

时间:2019-12-10 23:20:53 出处:经典散文阅读(143)

asp.net core web api 生成 swagger 文档Intro在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果接口多了就有点不适用了,没有接口文档会大大提高前后端的沟通成本。而 asp.net core 可以通过 Swashbuckle.AspNetCore 很方便的集成 swagger 文档,相比之下 nodejs(express) 和 swagger 集成就很麻烦了,大概这就是强类型语言的优势吧。C# 是最好的编程语言~~~集成 swagger配置 model 以及 api 项目生成 xml 文档在对应项目的项目文件中加入下面的代码 ,配置生成 xml 文档<PropertyGroup><GenerateDocumentationFile>true</GenerateDocumentationFile><NoWarn>$(NoWarn);1591</NoWarn></PropertyGroup>在 Web 项目上引用 Swashbuckle.AspNetCore配置 web 项目使用 swagger配置 ConfigureServices ,配置示例代码services.AddSwaggerGen(options =>{options.SwaggerDoc(ApplicationHelper.ApplicationName, new Info { Title = "活动室预约系统 API", Version = "1.0" });options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Notice).Assembly.GetName().Name}.xml")); //使用Model项目的xml文档options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(NoticeController).Assembly.GetName().Name}.xml"), true); //使用ApiController项目的xml文档});配置 Configure ,配置示例代码app.UseSwagger().UseSwaggerUI(c =>{// c.RoutePrefix = string.Empty; //配置swagger ui前缀,默认值是 "swagger",你可以使用 "string.Empty"来配置首页就是 swagger uic.SwaggerEndpoint($"/swagger/{ApplicationHelper.ApplicationName}/swagger.json", "活动室预约系统 API");c.DocumentTitle = "活动室预约系统 API";});现在重新启动项目,访问 "/swagger" 就可以看到效果了其他小技巧忽略某些api,可以在controller 上加Attribute[ApiExplorerSettings(IgnoreApi = true)],这个Attribute 支持继承,也就是说你可以在一个BaseController 上加这个 Attribute ,这样继承于这个 BaseController 的 Controller 的接口都不会显示在 swagger 文档中添加自定义请求头参数,可以自定义一个 OperationFilter定义 OperationFilter 示例public class AuthorizationOperationFilter : IOperationFilter{public void Apply(Operation operation, OperationFilterContext context){if (operation.Parameters == null){operation.Parameters = new List<IParameter>();}var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors;var isAuthorized = filterPipeline.Any(filter => filter.Filter is AuthorizeFilter);var allowAnonymous = filterPipeline.Any(filter => filter.Filter is IAllowAnonymousFilter);if (isAuthorized && !allowAnonymous){operation.Parameters.Add(new NonBodyParameter(){Name = "Authorization",In = "header",Type = "string",Description = "access token",Required = true});}}}public class ApiVersionOperationFilter : IOperationFilter{public void Apply(Operation operation, OperationFilterContext context){if (operation.Parameters == null){operation.Parameters = new List<IParameter>();}context.ApiDescription.TryGetMethodInfo(out var methodInfo);if (methodInfo.DeclaringType.IsDefined(typeof(ApiVersionAttribute), true)){operation.Parameters.Add(new NonBodyParameter(){Name = "Api-Version",In = "header",Type = "string",Description = "Api-Version",Required = true,Default = "1.0"});}}}配置 swagger 使用 OperationFilterservices.AddSwaggerGen(options =>{// ...options.OperationFilter<AuthorizationOperationFilter>();});更多技术及骚操作参考官方文档介绍 https://github.com/domaindrivendev/Swashbuckle.AspNetCore示例API 接口 swagger 文档 https://reservation.weihanli.xyz/swagger/index.html这个API 接口文档只显示了API接口,服务器端其他的Controller 使用了上面提到的 [ApiExplorerSettings(IgnoreApi = true)] 忽略了最近我的活动室预约的项目增加了一个前后端分离的 angular + marterial 的客户端 ,体验地址 https://reservation-client.weihanli.xyz/Referencehttps://github.com/domaindrivendev/Swashbuckle.AspNetCorehttps://github.com/WeihanLi/ActivityReservation/tree/dev/ActivityReservation

分享到:

温馨提示:以上内容和图片整理于网络,仅供参考,希望对您有帮助!如有侵权行为请联系删除!

友情链接: