.net core webapi 添加 swagger 调试

.net core webapi 添加 swagger 调试

开发环境：Visual Studio 2019

为解决前后端苦于接口文档与实际不一致、维护和更新文档的耗时费力等问题，swagger应运而生，同时也解决了接口测试问题。话不多说，直接说明应用步骤。

1. 新建一个ASP.NET Core Web API应用程序，版本选择.ASP.NET Core 3.1；
2. 通过Nuget安装包：Swashbuckle.AspNetCore，当前示例版本5.5.0；
3. 在Startup类的ConfigureServices方法内添加以下注入代码：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "API文档描述",
        Contact = new OpenApiContact
        {
            Email = "[email protected]",
            Name = "测试项目",
            //Url = new Uri("http://t.abc.com/")
        },
        License = new OpenApiLicense
        {
            Name = "BROOKE许可证",
            //Url = new Uri("http://t.abc.com/")
        }
    });              
});

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

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

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

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

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "API文档描述",
        Contact = new OpenApiContact
        {
            Email = "[email protected]",
            Name = "测试项目",
            //Url = new Uri("http://t.abc.com/")
        },
        License = new OpenApiLicense
        {
            Name = "BROOKE许可证",
            //Url = new Uri("http://t.abc.com/")
        }
    });
 
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

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

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

var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录
var xmlPath = Path.Combine(basePath, "CoreAPI_Demo.xml");
c.IncludeXmlComments(xmlPath, true);

同时，调整项目生成的XML文档文件路径为：…\CoreAPI_Demo\CoreAPI_Demo.xml

6. 隐藏相关接口
   对于不想暴漏给Swagger展示的接口，我们可以给相关Controller或Action头加上：[ApiExplorerSettings(IgnoreApi = true)]

7. 调整系统默认输出路径
   项目启动后，默认会访问自带的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