.net core 3.1简单swagger配置教程

前言

当今前后端分离开发已经成为一种大趋势，那后端开发人员给前端开发人员接口文档，无非就两种形式，手写接口文档跟在线接口文档。这时候引用swagger，让后端人员摆脱重复工作的麻烦。

亲测有效

开始

1、新建项目

随便新建个空的webapi项目

 

2、引入Swagger包。

.Net Core 中支持两个分别为Swashbuckle和NSwag。两者的配置大同小异。这里以Swashbuckle为例。

 

 

3、配置Swagger中间件

3.1 在Startup类ConfigureServices方法中添加Swagger服务并配置文档信息

 

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
// 注册Swagger服务
services.AddSwaggerGen(c =>
{
// 添加文档信息
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });
});
}

3.2 在 Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

 

//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui，指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

3.3 启动项目测试swagger是否配置成功
输入默认端口https://localhost:5001/swagger/index.html测试，当出现如图所示，则表示成功配置。

 

 

4、关键步骤（配置xml注释）

4.1右击项目=》属性=》生成，修改以下配置。

 

 4.2 重新打开Startup类，找到AddSwaggerGen（）方法中读取xml文件路径并启用

 

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
// 注册Swagger服务
services.AddSwaggerGen(c =>
{
// 添加文档信息
c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });

// 使用反射获取xml文件。并构造出文件的路径
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 启用xml注释. 该方法第二个参数启用控制器的注释，默认为false.
c.IncludeXmlComments(xmlPath, true);
});
}

这时候我们重新生成项目会发现项目根目录下产生一个xml文件

 

 

测试接口的注释信息

/// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}

测试结果如图，我们本次的swagger配置几乎就已经大功告成了。

 

注意事项

1、以上都是本地运行测试，假如要生成发布部署到服务器，会出错，是因为默认的xml不会生成到文件夹里，需要右击更改xml文件的属性

 

 

 2、以目前流行的三层开发模式，一般请求跟返回实体，我们会放在model层那边，因人而异，但假如我们的Controller层引用任何一个程序集的实体，同时也想让该程序集的实体注释生成，同样也需要配置开启xml注释，如图所示

 

 响应实体类

/// <summary>
/// 返回实体
/// </summary>
public class SwaggerResponse
{

/// <summary>
/// 编码
/// </summary>
public int code { get; set; }
/// <summary>
/// 数据
/// </summary>
public string data { get; set; }
}

控制器方法调整

/// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
[HttpGet("{id}")]
public SwaggerResponse Get(int id)
{
var obj = new SwaggerResponse { code = 200, data = "hello,world!" };
return obj;
}

 

重新运行项目，如图所示则表示成功。

 

 

————————————————
版权声明：本文为CSDN博主「你加班改的代码真不是我写的」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/shaojiayong/article/details/114857949