当前位置：首页 > news >正文

.net core webapi 添加 swagger 调试

news 2026/7/4 9:57:51

.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{Title="My API",Version="v1",Description="API文档描述",Contact=newOpenApiContact{Email="5007032@qq.com",Name="测试项目",//Url = new Uri("http://t.abc.com/")},License=newOpenApiLicense{Name="BROOKE许可证",//Url = new Uri("http://t.abc.com/")}});});

Startup类的Configure方法添加如下代码：

//配置Swaggerapp.UseSwagger();app.UseSwaggerUI(c=>{c.SwaggerEndpoint("/swagger/v1/swagger.json","My API V1");c.RoutePrefix="api";// 如果设为空，访问路径就是根域名/index.html，设置为空，表示直接在根域名访问；想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html});

Ctrl+F5进入浏览，按上述配置修改路径为：http://localhost:***/api/index.html，即可看到Swagger页面：

然而到这里还没完，相关接口的注释说明我们看不到，通过配置XML文件的方式继续调整代码如下，新增代码见加粗部分：

services.AddSwaggerGen(c=>{c.SwaggerDoc("v1",newOpenApiInfo{Title="My API",Version="v1",Description="API文档描述",Contact=newOpenApiContact{Email="5007032@qq.com",Name="测试项目",//Url = new Uri("http://t.abc.com/")},License=newOpenApiLicense{Name="BROOKE许可证",//Url = new Uri("http://t.abc.com/")}});varxmlFile=$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";varxmlPath=Path.Combine(AppContext.BaseDirectory,xmlFile);c.IncludeXmlComments(xmlPath);});

上述代码通过反射生成与Web API项目相匹配的XML文件名，AppContext.BaseDirectory属性用于构造 XML 文件的路径，关于OpenApiInfo内的配置参数用于文档的一些描述，在此不作过多说明。
然后右键Web API项目、属性、生成，配置XML文档的输出路径，以及取消不必要的XML注释警告提醒（增加1591）：

这样，我们以三斜杠（///）方式给类方法属性等相关代码添加注释后，刷新Swagger页面，即可看到注释说明。
如果不想将XML文件输出为debug下的目录，譬如想要放在项目根目录（但不要修改成磁盘绝对路径），可调整相关代码如下，xml文件的名字也可以改成自己想要的：

varbasePath=Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录varxmlPath=Path.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"}}}}