Swagger UI in AspNetCore WebAPI
swagger其实包含了三个部分,分别是swagger editor文档接口编辑器,根据接口文档生成code的swagger codegen,以及生成在线文档的swagger ui。
在aspnetcore中通常使用microsoft封装的swashbuckle来使用swagger ui,这是一个aspnetcore的中间件。和其他中间件一样都是分为register和use两个部分。
installation
vs中很简单,直接用nuget安装swashbuckle.aspnetcore即可。
或者使用命令行: dotnet add package --version xxx swashbuckle.aspnetcore
register
所有swagger ui注册的configue相关的内容都放在addswaggergen这个方法里面:
namespace microsoft.extensions.dependencyinjection { public static class swaggergenservicecollectionextensions { public static iservicecollection addswaggergen(this iservicecollection services, action<swaggergenoptions> setupaction = null); public static void configureswaggergen(this iservicecollection services, action<swaggergenoptions> setupaction); } }
addswaggergen这个方法主要用户注册中间件的时候添加一些参数,其中重要的有:
swaggerdoc:添加一个swagger document,主要用户存储生成出来的openapi文档。以及一些文档基本信息,如:作者、描述、license等。
xxxfilter:自定义filter,xxx为swagger中的对象,当xxx创建完成后,filter可以定义操作对xxx进行处理。
addsecuritydefinition和addsecurityrequirement:用于给swagger添加验证的部分。
includexmlcomments:为openapi提供注释内容的xml,需要在ide里面配置生成对应的xml文件。(当vs中使用生成xml文档文件这个功能的时候,如果有方法没有添加注释,vs会有提示,如果要避免这个提示,可以在下图中的suppress warnings中把1591禁掉。)
use
routetemplate:useswagger中配置swagger页面路由信息。
routeprefix:类似sharepoint中的host name,默认为swagger,如果不需要可以设置为“”。
swaggerendpoint:openapi文件的访问url,这个url和routetemplate以及swaggerdoc的name一定要一致,不然就会有page not found的错。
当请求openapi文件的时候,会从swaggerendpoint配置的url中配合routetemplate一起解析document的name。
下面是routetemplate的配置:
1 app.useswagger(option => 2 { 3 option.routetemplate = string.format("{0}/{1}", prefix, "{documentname}/swagger.json"); 4 });
解析document name的过程。
1 private bool requestingswaggerdocument(httprequest request, out string documentname) 2 { 3 documentname = null; 4 if (request.method != "get") return false; 5 6 var routevalues = new routevaluedictionary(); 7 if (!_requestmatcher.trymatch(request.path, routevalues) || !routevalues.containskey("documentname")) return false; 8 9 documentname = routevalues["documentname"].tostring(); 10 return true; 11 }
上一篇: 一加8 360度高清渲染图曝光:骁龙865、挖孔屏设计
下一篇: 自制烤鱿鱼丝,给你介绍制作的小技巧
推荐阅读
-
ASP.NET Core 2.2 WebApi 系列【四】集成Swagger
-
java swagger ui 添加header请求头参数的方法
-
swagger 集成后发布到服务器报错[Could not find file 'D:\\home\\site\\wwwroot\\bin\\WebAPI.XML]
-
AspNetCore网关集成Swagger访问使用IdentityServer保护的webapi项目
-
C# WebAPI中使用Swagger
-
循序渐进学.Net Core Web Api开发系列【2】:利用Swagger调试WebApi
-
Swagger UI改造 增加 Token验证、显示控制器注释、自定义泛型缓存应用、
-
Swagger实例分享(VS+WebApi+Swashbuckle)
-
Flask 系列之构建 Swagger UI 风格的 WebAPI
-
ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了