.net core 3.1 webapi接口项目框架搭建一：swagger

新建项目

1. “文件” —>“新建”—>“新建项目”
   
2. 按照提示 “下一步” ，最后选择一下 “项目模板”（API）
   

引用swagger依赖包

在NuGet包管理器中直接搜索Swashbuckle.AspNetCore安装即可

配置服务

在Startup.cs ConfigureServices 方法中 配置swagger 服务

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo {
         Version = "v1",   //版本 
         Title = $".net core 接口文档-NetCore3.1",  //标题
          Description = $".net core Http API v1"    //描述
     });
});

添加中间件

在 Startup.cs 中的 Configure方法中 启动swagger 中间件

 // 添加Swagger有关中间件
  app.UseSwagger();
  app.UseSwaggerUI(c =>
  {
     c.SwaggerEndpoint("/swagger/v1/swagger.json", ".net core Http API v1");
  });

修改launchSettings.json 文件

将启动页设置 为“swagger”

查看效果

1. “开始” —> cmd —> cd “项目所在位置”
2. 执行 “dotnet run” 命令
   
3. 浏览器 打开 http://localhost:5000/swagger/index.html

启动XML注释

右键web 项目名称—>属性---->生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个,如下图所示

忽视Swagger注释警告 ： 在取消显示警告中添加 1591

配置服务

在Startup.cs 文件中的 ConfigureServices 方法中的 swagger 服务中 添加如下代码：

//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
//这个就是刚刚配置的xml文件名
var xmlPath = Path.Combine(basePath, "Core.xml");
//默认的第二个参数是false,对方法的注释
//c.IncludeXmlComments(xmlPath);
//这个是controller的注释
c.IncludeXmlComments(xmlPath, true);

实体启动XML注释

1. 右键 实体 项目 ----> 启动 输出xml
2. 右键 xml 文件 —> 属性 —> 始终复制=
3. 配置服务 ，Startup.cs 文件中的 ConfigureServices 方法中添加如下代码：

//设置Model.xml 的文件属性 为 “始终复制”
var modelXmlPath = Path.Combine(basePath, "Model.xml");
c.IncludeXmlComments(modelXmlPath);

//设置Enum.xml 的文件属性 为 “始终复制”
var enumXmlPath = Path.Combine(basePath, "Enum.xml");
c.IncludeXmlComments(enumXmlPath);