网上看了一些Abp vNext引用swagger的教程,大致流程都差不多,就是生成每一层对应的xml然后使用IncludeXmlComments方法来引用,后面亲自实践发现有些差异和要点,在此记录一下。
基本步骤:
- 右击项目解决方案,属性-生成-输出-勾选XML文档文件,删除路径信息仅保留xml文件名称。例如:xxx.Application.xml。
- hostmodule下,AddSwaggerGen内添加以下代码:
1 context.Services.AddSwaggerGen(options=> { 3 // 添加swagger-API方法注释 4 var xmlapppath = Path.Combine(AppContext.BaseDirectory, "xxx.Application.xml"); 5 if (File.Exists(xmlapppath)) 6 options.IncludeXmlComments(xmlapppath, true); 7 8 // 添加swagger-DTO参数注释 9 var xmlContractspath = Path.Combine(AppContext.BaseDirectory,"xxx.Application.Contracts.xml"); 10 if (File.Exists(xmlContractspath)) 11 options.IncludeXmlComments(xmlContractspath, true); 12 13 // 添加swagger-自定义控制器注释 14 var xmlapipath = Path.Combine(AppContext.BaseDirectory, "xxx.WebAPI.xml"); 15 if (File.Exists(xmlapipath)) 16 options.IncludeXmlComments(xmlapipath , true); 17 });
- 引用路径不要采用本地路径,可以使用AppContext.BaseDirectory来拼接地址以避免发布时遇到问题。
- xxx.Application.xml添加引用后可以生成API方法注释,但是并没有DTO参数注释,因为dto定义都在应用服务抽象层,需要添加xxx.Application.Contracts.xml后才会有参数注释。
- 因为一般使用的是动态API,如果你有自定义的controller方法,需要添加xxx.HttpApi.xml进来才能看到自定义控制器方法的注释。
- 配置生成XML文件时,注意配置release环境下的输出,不要只配Debug模式。