.net core webapi 添加 swagger 调试

📅 2026/7/4 9:58:13 👁️ 次浏览

.net core webapi 添加 swagger 调试开发环境Visual Studio 2019为解决前后端苦于接口文档与实际不一致、维护和更新文档的耗时费力等问题swagger应运而生同时也解决了接口测试问题。话不多说直接说明应用步骤。新建一个ASP.NET Core Web API应用程序版本选择.ASP.NET Core 3.1通过Nuget安装包Swashbuckle.AspNetCore当前示例版本5.5.0在Startup类的ConfigureServices方法内添加以下注入代码services.AddSwaggerGen(c{c.SwaggerDoc(v1,newOpenApiInfo{TitleMy API,Versionv1,DescriptionAPI文档描述,ContactnewOpenApiContact{Email5007032qq.com,Name测试项目,//Url new Uri(http://t.abc.com/)},LicensenewOpenApiLicense{NameBROOKE许可证,//Url new Uri(http://t.abc.com/)}});});Startup类的Configure方法添加如下代码//配置Swaggerapp.UseSwagger();app.UseSwaggerUI(c{c.SwaggerEndpoint(/swagger/v1/swagger.json,My API V1);c.RoutePrefixapi;// 如果设为空访问路径就是根域名/index.html设置为空表示直接在根域名访问想换一个路径直接写名字即可比如直接写c.RoutePrefix swagger; 则访问路径为根域名/swagger/index.html});CtrlF5进入浏览按上述配置修改路径为http://localhost:***/api/index.html即可看到Swagger页面然而到这里还没完相关接口的注释说明我们看不到通过配置XML文件的方式继续调整代码如下新增代码见加粗部分services.AddSwaggerGen(c{c.SwaggerDoc(v1,newOpenApiInfo{TitleMy API,Versionv1,DescriptionAPI文档描述,ContactnewOpenApiContact{Email5007032qq.com,Name测试项目,//Url new Uri(http://t.abc.com/)},LicensenewOpenApiLicense{NameBROOKE许可证,//Url new Uri(http://t.abc.com/)}});varxmlFile${Assembly.GetExecutingAssembly().GetName().Name}.xml;varxmlPathPath.Combine(AppContext.BaseDirectory,xmlFile);c.IncludeXmlComments(xmlPath);});上述代码通过反射生成与Web API项目相匹配的XML文件名AppContext.BaseDirectory属性用于构造 XML 文件的路径关于OpenApiInfo内的配置参数用于文档的一些描述在此不作过多说明。然后右键Web API项目、属性、生成配置XML文档的输出路径以及取消不必要的XML注释警告提醒增加1591这样我们以三斜杠///方式给类方法属性等相关代码添加注释后刷新Swagger页面即可看到注释说明。如果不想将XML文件输出为debug下的目录譬如想要放在项目根目录但不要修改成磁盘绝对路径可调整相关代码如下xml文件的名字也可以改成自己想要的varbasePathPath.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录varxmlPathPath.Combine(basePath,CoreAPI_Demo.xml);c.IncludeXmlComments(xmlPath,true);同时调整项目生成的XML文档文件路径为…\CoreAPI_Demo\CoreAPI_Demo.xml隐藏相关接口对于不想暴漏给Swagger展示的接口我们可以给相关Controller或Action头加上[ApiExplorerSettings(IgnoreApi true)]调整系统默认输出路径项目启动后默认会访问自带的weatherforecast如果想调整为其他路径譬如打开后直接访问Swagger文档那么调整Properties目录下的launchSettings.json文件修改launchUrl值为api前述配置的RoutePrefix值{$schema:http://json.schemastore.org/launchsettings.json,iisSettings:{windowsAuthentication:false,anonymousAuthentication:true,iisExpress:{applicationUrl:http://localhost:7864,sslPort:0}},profiles:{IIS Express:{commandName:IISExpress,launchBrowser:true,launchUrl:api,environmentVariables:{ASPNETCORE_ENVIRONMENT:Development}},CoreApi_Demo:{commandName:Project,launchBrowser:true,launchUrl:api,applicationUrl:http://localhost:5000,environmentVariables:{ASPNETCORE_ENVIRONMENT:Development}}}}原文地址: https://wuyaogexing.com/70/1138699.html#_label0

相关新闻