Abp vNext 关于引用swagger注释补充

网上看了一些Abp vNext引用swagger的教程，大致流程都差不多，就是生成每一层对应的xml然后使用IncludeXmlComments方法来引用，后面亲自实践发现有些差异和要点，在此记录一下。

基本步骤：

1. 右击项目解决方案，属性-生成-输出-勾选XML文档文件，删除路径信息仅保留xml文件名称。例如xxx.Application.xml。
2. hostmodule下，AddSwaggerGen内添加以下代码：

context.Services.AddSwaggerGen(options=> {
    ......
    // 添加swagger-API方法注释
    var xmlapppath = Path.Combine(AppContext.BaseDirectory, "xxx.Application.xml");
    if (File.Exists(xmlapppath))
        options.IncludeXmlComments(xmlapppath, true);
 
    // 添加swagger-DTO参数注释
    var xmlContractspath = Path.Combine(AppContext.BaseDirectory,             "xxx.Application.Contracts.xml");
    if (File.Exists(xmlContractspath))
        options.IncludeXmlComments(xmlContractspath, true);
 
    // 添加swagger-自定义控制器注释
    var xmlapipath = Path.Combine(AppContext.BaseDirectory, "xxx.WebAPI.xml");
    if (File.Exists(xmlapipath))
        options.IncludeXmlComments(xmlapipath , true);
});

1. 引用路径不要采用本地路径，可以使用AppContext.BaseDirectory来拼接地址以避免发布时遇到问题。
2. xxx.Application.xml添加引用后可以生成API方法注释，但是并没有DTO参数注释，因为dto定义都在应用服务抽象层，需要添加xxx.Application.Contracts.xml后才会有参数注释。
3. 因为一般使用的是动态API，如果你有自定义的controller方法，需要添加xxx.HttpApi.xml进来才能看到自定义控制器方法的注释。
4. 配置生成XML文件时，注意配置release环境下的输出，不要只配Debug模式。

---

ABP 为SWAGGER接口页添加详细注释

从Abp官网创建完项目之后，启动之后，Swagger的接口说明页，默认是没有接口说明的，这样是很不友好的，也不利于接口调用者的使用，所以，我们要实现Swagger页面的接口注释功能。

首先，我们看一下默认启动后，Swagger的接口页面，标红的是我们自己写的获取所有组织机构的接口，默认是没有注释的。

接下来，我们选中我们Application层的项目，右键“属性”，将输出路径选择为“bin\Debug\”，然后再勾选为Xml生成文档，如下图所示。

接下来，在你的 项目名.WEB.HOST 的STARTUP目录下，找到STARTUP.CS类，在它的CONFIGURESERVICES方法中，找到配置SWAGGER的代码块(SERVICES.ADDSWAGGERGEN)，将生成的XML配置进去。核心代码如下：

var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
var xmlPath = Path.Combine(basePath, "HealthCenter.Web.Host.xml");   //  添加 swagger xml 注释  这个xml文件开始是不存在的写上项目名.xml即可
   options.IncludeXmlComments(xmlPath);

然后再启动项目，可以看到我们的接口有注释了