asp.net core web api 生成 swagger 文档
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 ui c.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 使用 operationfilter
services.addswaggergen(options => { // ... options.operationfilter<authorizationoperationfilter>(); });
-
更多技术及骚操作参考官方文档介绍 https://github.com/domaindrivendev/swashbuckle.aspnetcore
示例
api 接口 swagger 文档
这个api 接口文档只显示了api接口,服务器端其他的controller 使用了上面提到的 [apiexplorersettings(ignoreapi = true)]
忽略了
最近我的活动室预约的项目增加了一个前后端分离的 angular + marterial 的客户端,体验地址
reference
推荐阅读
-
ASP.NET Web API如何将注释自动生成帮助文档
-
SpringBoot+Swagger-ui自动生成API文档
-
Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解
-
或许是你应该了解的一些 ASP.NET Core Web API 使用小技巧
-
SpringBoot结合Swagger2自动生成api文档的方法
-
Asp.net core WebApi 使用Swagger生成帮助页实例
-
Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解
-
ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介
-
Asp.net core WebApi 使用Swagger生成帮助页实例
-
ASP.NET Core Web API 最佳实践指南