Asp.net corewebapi使用斯瓦格生成帮助页面示例

最近，我们的团队正在经历。net核心，web开发已经向前端和后端分离的技术架构发展。我们主要在后台使用ASP.NET Core Web API进行开发，这种低效存在于每次开始的调试和与前端人员的沟通中。有一次看微软ASP.NET Core的官方文档，发现霸气是好事。然后，将该技术引入到实际项目中。测试我们开发人员编写的API的过程大大简化，前端人员也可以根据我们提供的swagger帮助页面测试一些前端代码，大大提高了前端和后端的开发效率。接下来，我将以自己的真实在线项目，一步步讲解如何将swagger引入ASP.NET核心Web API。(也可以参考微软官方文档：https://docs . Microsoft.com/zh-cn/aspnet/core/tutories/web-API-help-pages-using-swag)

首先，介绍一下斯瓦格Nuget包

右键单击wepapi项目的依赖项，点击管理Nuget包，如下图所示：

在打开的NuGet包程序管理界面，输入：Swashbuckle。该软件包的当前版本是1.0.0，然后单击安装。

安装后，需要在项目的Startup.cs文件中进行配置。

第二，配置Swagger

打开Startup.cs文件，并在ConfigureServices方法中添加以下代码：

services . addswaggergen(c={ c . swaggerdoc(' v1 '，newinfo {version=' v1 '，title=' twbusmanagement接口文档'，Description='用于twbusmanagement的RESTful API '，TermsOfService='None '，Contact=new Contact { Name=' Alvin _ Su '，Email='[emailprotected]'，URl=' ' })；//为swagger json和ui设置注释路径。var basePath=PlatformServices。默认值。application . application base path；var xmlPath=路径。Combine(basePath，' twbusapi . XML ')；c . includexlcomments(XMlpath)；//c . operationfilterhttpheaderproperties()；//添加httpHeader参数})；请注意，前面代码的最后三行是api描述文档xml的生成地址和文件名，需要在项目属性中进行配置。下图：

此外，在上图中，在未显示的警告中添加1591代码，可以过滤掉一些在类名中没有写注释的报警消息。

最后，需要在Configure方法中添加以下代码，注意在app之前必须添加以下代码。UseMvc():

//使中间件能够将生成的Swagger作为JSON端点服务。app。useswaggle()；//启用中间件服务霸气ui (HTML、JS、CSS等)。)，指定斯瓦格JSON端点。app。UseSwaggerUI(c={ c . SwaggerEndpoint('/swagger/v1/swagger . JSON '，' twbus management API V1 ')；c . ShowRequestHeaders()；});完成上述配置后，可以使用Swagger生成的帮助页面。运行项目后，您可以通过在浏览器地址中添加后缀/swag跳转到帮助页面：

当然，我们开发人员也不希望在开发项目的过程中，每次都要手动输入地址才能跳转到帮助页面，太麻烦了。我们可以借助visual studio进行跳转，如下图所示：

打开launchSettings.json文件，将webapi项目的启动路径设置为swag。这样，每个调试和运行的项目都会自动跳转到swagger帮助页面

三、招摇的一些高级用法

swag非常强大，不仅有一些帮助页面信息，还有api调试。这样，我们就可以在不使用第三方工具(如postman)的情况下调试webapi。swag被配置为输入一些http头信息，如授权认证信息。下面我们来解释一下具体的配置。

首先，我们需要创建一个新的类HttpHeaderOperation，并让它继承IOperationFilter接口。接口需要引入命名空间swashbuck . aspnetcore . swaggergen，实现接口方法Apply的代码如下：

公共类httpadeproperties : iooperationfilter { public void Apply(Operation Operation，OperationFilterContext){ if(Operation .参数==null){ 0操作。参数=新的ListIParameter()；} var actionAttrs=context .ApiDescription。操作属性()；var isAuthorized=actionAttrs .any(a=a . GetType()==(authorizeAttribute)的类型)；if(is authorized==false)//提供行为都没有权限特性标记，检查控制器有没有{ var controllerAttrs=context .API描述。控制器属性()；isAuthorized=controllerAttrs .any(a=a . GetType()==(authorizeAttribute)的类型)；} var是allowanonymous=action attrs .any(a=a . GetType()==(allowanOnymousAttribute)的类型)；if(Isauthorized IsallOutLook==false){ operation .参数。添加（新的非数据库参数(){名称='授权',//添加批准头部参数In='header '，Type='string '，Required=false })；} } }然后在Startup.cs中的配置服务方法，找到之前的AddSwaggerGen代码段，在最后添加如下代码：

c . operationfilterhttpaderproperties()服务AddSwaggerGen(c={ c . SwaggerDoc(' v1)，新信息{版本='v1 '，标题='TwBusManagement '接口文档，描述='用于TwBusManagement的RESTful API '，TermsOfService='None '，Contact=new Contact { Name=' Alvin _ Su '，Email='[emailprotected]'，Url=' ' } })；//为斯瓦格json和用户界面设置注释路径var basePath=PlatformServices .默认值申请。应用程序基本路径；var xmlPath=路径Combine(basePath，' twbusapi。XML ')；c . includexcmments(XMlpath)；c . operationfilterhttpaderproperties()；//添加httpHeader参数});这样，我们允许webapi项目后，就可以输入批准头部参数了。如下图：

更多关于时髦的的用法可以参考https://github.com/domaindrivendev/Swashbuckle.AspNetCore以及微软文档：https://个文档。微软。com/zh-cn/aspnet/core/tutorials/web-API-帮助页-使用-swag

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持我们。