网上看了一些Abp vNext
引用swagger
的教程,大致流程都差不多,就是生成每一层对应的xml
然后使用IncludeXmlComments
方法来引用,后面亲自实践发现有些差异和要点,在此记录一下。
基本步骤:
- 右击项目解决方案,属性-生成-输出-勾选
XML
文档文件,删除路径信息仅保留xml
文件名称。例如xxx.Application.xml
。 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);
});
- 引用路径不要采用本地路径,可以使用
AppContext.BaseDirectory
来拼接地址以避免发布时遇到问题。 xxx.Application.xml
添加引用后可以生成API方法注释,但是并没有DTO
参数注释,因为dto
定义都在应用服务抽象层,需要添加xxx.Application.Contracts.xml
后才会有参数注释。- 因为一般使用的是动态API,如果你有自定义的
controller
方法,需要添加xxx.HttpApi.xml
进来才能看到自定义控制器方法的注释。 - 配置生成
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);
然后再启动项目,可以看到我们的接口有注释了