仓储三层实践：02swagger配置注释文件

一、新建分支02swagger

git checkout -b 02swagger

二、生成注释的xml文件

1. vs打开解决方案，找到项目Nest.WebApi名称右键点击属性

2. 切换到生成选项卡

3. 拉到下面输出位置，把xml文档文件的选项框打上钩

4. 把后面文本框的绝对路径改为相对路径..Nest.WebApiNest.WebApi.xml(相对路径移植性好点)

5. 再往上拉到错误和警告位置，在取消错误和警告后面的文本框里追加;1591（压制警告，第四步作完要求所有的public修饰的类和方法都必须带注释，不然一堆感叹号的警告）

也就是最终Nest.WebApi的项目文件如下：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    <RootNamespace>Nest</RootNamespace>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>..Nest.WebApiNest.WebApi.xml</DocumentationFile>
    <NoWarn>1701;1702;1591</NoWarn>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Autofac.Extensions.DependencyInjection" Version="7.1.0" />
    <PackageReference Include="Autofac.Extras.DynamicProxy" Version="6.0.0" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..Nest.ApplicationNest.Application.csproj" />
  </ItemGroup>

</Project>

另外Nest.Core项目也同上操作生成xml文件，结果如下

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    <RootNamespace>Nest</RootNamespace>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>..Nest.CoreNest.Core.xml</DocumentationFile>
    <NoWarn>1701;1702;1591</NoWarn>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="5.0.6" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="5.0.6" />
  </ItemGroup>

</Project>

三、swagger的注册配置

1. 打开Nest.WebApi项目的Startup.cs文件，修改ConfigureServices方法，主要是增加两个xml文件，顺带把文档的信息写入

public void ConfigureServices(IServiceCollection services)
{

    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Nest.WebApi", Version = "v1" });
        // 加载Nest.WebApi项目的xml文件，第二个参数true代表显示控制器上的注释
        c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Nest.WebApi.xml"), true);
        // 加载Nest.WebApi项目的xml文件，第二个参数true代表显示控制器上的注释
        c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Nest.Core.xml"));
    });
}

2. 在Nest.Core随便建个类，打上///注释，Nest.WebApi随便建个新的控制器，打上///，然后就可以运行看看效果，具体代码直接看仓库

四、提交代码，结束

# 查看git状态
git status
# 添加所有变化到暂存区
git add .
# 提交暂存区到本地仓库
git commit -m "添加swagger注释文件"
# 切换到master主分支
git checkout master
# 合并到主分支
git merge 02swagger
# 推送master分支到远程仓库
git push
# 切换到02swagger分支
git checkout 02swagger
# 推送02swagger分支到远程仓库
git push -u origin 02swagger

下篇预告：仓储三层实践：03jwt身份验证