.net Core 集成 swagger

.net core 集成swagger 自动生成API文档

开发环境：win10, vs2019, .net 5.0

首先新建一个ASP.NET Core Web API 项目
现在VS Web API 项目的模板已经集成了OpenAPI支持，该模板就是基于Swagger的，可以直接选择，也可以不勾选，在创建项目后自己添加。

这里主要有两段代码在startup.cs中，分别是 ConfigureServices 方法中的

	services.AddSwaggerGen(c =>
    {
    	c.SwaggerDoc("v1", new OpenApiInfo { Title = "SwaggerDemo", Version = "v1" });
    });

和 Configure 方法中的

	if (env.IsDevelopment())
	{
     	app.UseDeveloperExceptionPage();
        app.UseSwagger();
        app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerDemo v1"));
    }

这里需要注意的是 app.UseSwagger 和 app.UseSwaggerUI 是放在开发环境中的，因为接口文档一般仅用于开发测试阶段，在生产环境一般都不会暴露出去。

还有一个注意项是
以上都是模板自动生成的代码，我们直接F5 运行项目，就会直接打开接口文档的地址，因为在项目的 launchSettings.json 文件中已经设置了默认的URL为 swagger 的地址

接口文档打开的效果如果

这里可以看到接口文档并没有任何注释，会导致阅读困难；接下来将添加swagger 文档的接口注释。
首先需要设置项目属性生成xml文档文件；例如：

这里xml文档的输出地址也可指定为其他路径
注意：当设置了输出xml文档后，vs会检测代码文件中类，方法，属性是否增加了xml注释，如果没有注释则会提示警告，如图：

如果不想出现这个警告可以在项目属性中配置取消显示警告中添加 1591，如图

这样就算没有添加xml注释也不会提示警告了！
到此为止已经生成了xml文档，接下来就是怎么把xml文档加载到swagger上了；
只需要改造一下 Startup.cs 中 ConfigureServices 即可，代码如下

services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("v1", new OpenApiInfo { Title = "SwaggerDemo", Version = "v1" });

	// 获取xml文件名
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    // 获取xml文件路径
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    if (File.Exists(xmlPath))
    {
    	// 添加控制器层注释，true表示显示控制器注释
        c.IncludeXmlComments(xmlPath, true);
    }

   // Dto xml注释
   var dtoXmlFile = $"{ Assembly.Load("SwaggerModel").GetName().Name}.xml";
   var dtoXmlPath = Path.Combine(AppContext.BaseDirectory, dtoXmlFile);
   if (File.Exists(xmlPath))
   {
        c.IncludeXmlComments(dtoXmlPath);
   }
});

这里添加了两个xml文档，因为正式项目接口和数据传输对象会在不同的项目下。
然后重新启动项目，我们可以看到项目已经显示了注释信息，这样阅读起来就更方便了