Asp.NET core 6：添加Swagger，简化教程和常见问题处理

 

 

--------------- ≯ 安装 ≮ ---------------

一、添加包：

Swashbuckle.Asp.NetCore

二、 编辑Program.cs

1、添加到启动：

 

 

//Swagger配置
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "APP更新 API",
Description = "",
});

options.CustomSchemaIds(x => x.FullName);
options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

// using System.Reflection;
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename),true);
});

2、生成项目的xml文件

Web项目属性

 

 

 

3、强制显示（有的教程没有这一步）

 

 

 

if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(
c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
}
);
}

 4、修改链接：

修改文件：

<项目地址>\Views\Shared\_layout.cshtml

添加代码：

 

 

<li class="nav-item">
<a class="nav-link text-dark" href="/Swagger">Swagger</a>
</li>

(注意、修改之后不会立即更新，需要按下 VS 里面的【热重载】按钮)

--------------- ≯ 常见问题 ≮ ---------------

一、显示控制器上面的注释。

1、控制器上添加 注释：

 

/// <summary>
/// 类注释、控制器注释
/// </summary>

2、Program.cs

开启控制器注释参数，第2个参数显示声明为 true

options.IncludeXmlComments(<地址>,【true】）

 

二、“ Internal Server Error /swagger/v1/swagger.json ”错误

原因：

某个类的方法或者控制器的Action，包括基类当中的，没有声明 【options】。

解决办法： 

给相应的类、方法添加

[HttpGet]
[HttpPost]

或者把方法改为protected.

在类或者方法上面添加声明：

  [ApiExplorerSettings(IgnoreApi = true)]

 

三、引用了一个包含多个public方法的基类，怎么样在Swagger当中屏蔽基类的public方法

基类上声明：

  [ApiExplorerSettings(IgnoreApi = true)]

 

 

 

派生类声明：

[ApiExplorerSettings(IgnoreApi = false)]

 

 

四、使用了当中Web项目（asp.net core项目）以外类库里面的Model类，希望在Swagger里面显示Model类的注释和说明：

首先让model类自动生成xml

然后在Program.cs添加处理：

 

 

 

五、数据自动校验（模型绑定）和默认值：

 

 

 

/// <summary>
/// 手机号码
/// </summary>
[DefaultValue("13311111111")]
[Required(ErrorMessage = "手机号码不能为空")]
[Phone(ErrorMessage = "手机号码格式不对")]
public string Mobile { get; set; }

 

 

最后付后一个代码示例：

下载地址