前言
本来在Swagger的基础上,前后端开发人员在开发生产期间,可以借此进行更加便捷的沟通交流。可是总有些时候,遇到一些难缠的,又不讲道理,偏偏觉得将Swagger文档地址丢给客户会不够正式!死活要一份word文档。
可是这个时候,如果接口数量上百个,甚至更多,一个一个手动输入word,那将是一笔耗时的工作。但却有什么办法可以解决呢?
对了,利用Swagge生成的Json文件转换为word文档不就可以了吗?
思路
1. 获取Swagger接口文档的Json文件
2. 解析Json文件数据填充到Html的表格中
3.根据生成的html转work文档
开始
一、根据Swagger版本获取Json数据
1.通过Swagger源码文件可以看到
可以拿到swagger生成的文档数据,所以我们可以新建一个控制器SwaggerController.cs,
private readonly SwaggerGenerator _swaggerGenerator; public SwaggerController(SwaggerGenerator swaggerGenerator) { _swaggerGenerator = swaggerGenerator; } /// /// 导出文件 /// /// 文件类型 /// 版本号V1 /// [HttpGet] public FileResult ExportWord(string type,string version) { string contenttype = string.Empty; var model = _swaggerGenerator.GetSwagger(version); //1. 根据指定版本获取指定版本的json对象。 }
2. 在Startup.cs文件中,利用net core的ioc容器,注入SwaggerGenerator实例化,这样在后面的调用中可以直接使用这个方法
services.AddScoped(); //注入SwaggerGenerator,后面可以直接使用这个方法
二、文件数据填充到Html的表格中
根据上面获取的model文件数据,这个时候,我们利用Razor文件,结合html的table模板,将数据遍历填充到页面中,生成完整的页面
Html模板
@using Swashbuckle.AspNetCore.Swagger; Swagger API文档代码文件
Word接口文档
@Model.Info.Title
接口文档 @Model.Info.Version
联系方式
作者:@Model.Info.Contact.NameSend email to Xunit.Core
@Model.Info.Contact.Name - Website
接口描述
@Model.Info.Description
说明 类型 @foreach (var item in Model.Paths) { if (item.Value.Operations != null) { foreach (var operation in item.Value.Operations) {
@operation.Value.Summary
URL @item.Key 请求方式 @operation.Key @if (operation.Value.Parameters != null && operation.Value.Parameters.Count > 0) { 参数名 参数类型 是否必填 说明 @foreach (var param in operation.Value.Parameters) { @param.Name @param.In @param.Required @param.Description } } 状态码 说明 @if (operation.Value.Responses != null && operation.Value.Responses.Count > 0) { foreach (var response in operation.Value.Responses) { @response.Key @response.Value.Description } } 示例 请求参数 返回值} } }
将数据遍历到静态页面中,
/// /// 将数据遍历静态页面中 /// /// 静态页面地址 /// 获取到的文件数据 /// public static string GeneritorSwaggerHtml(string templatePath, OpenApiDocument model) { var template = System.IO.File.ReadAllText(templatePath); var result = Engine.Razor.RunCompile(template, "i3yuan", typeof(OpenApiDocument), model); return result; }
三、根据生成的html转work文档
/// /// 静态页面转文件 /// /// 静态页面html /// 文件类型 /// 上下文类型 /// public Stream SwaggerConversHtml(string html, string type, out string contenttype) { string fileName = Guid.NewGuid().ToString() + type; //文件存放路径 string webRootPath = _hostingEnvironment.WebRootPath; string path = webRootPath + @"FilesTempFiles"; var addrUrl = path + $"{fileName}"; FileStream fileStream = null; var provider = new FileExtensionContentTypeProvider(); contenttype = provider.Mappings[type]; try {if (!Directory.Exists(path)){Directory.CreateDirectory(path);}var data = Encoding.Default.GetBytes(html);var stream = ByteHelper.BytesToStream(data);//创建Document实例Document document = new Document();//加载HTML文档document.LoadFromStream(stream, FileFormat.Html, XHTMLValidationType.None);//保存为Worddocument.SaveToFile(addrUrl, FileFormat.Docx);document.Close();fileStream = File.Open(addrUrl, FileMode.OpenOrCreate);var filedata = ByteHelper.StreamToBytes(fileStream);var outdata = ByteHelper.BytesToStream(filedata);return outdata; } catch (Exception) {throw; } finally {if (fileStream != null)fileStream.Close();if (File.Exists(addrUrl))File.Delete(addrUrl);//删掉文件 } }
public class ByteHelper { public static byte[] StreamToBytes(Stream stream) { byte[] bytes = new byte[stream.Length]; stream.Read(bytes, 0, bytes.Length); // 设置当前流的位置为流的开始 stream.Seek(0, SeekOrigin.Begin); return bytes; } /// 将 byte[] 转成 Stream public static Stream BytesToStream(byte[] bytes) { Stream stream = new MemoryStream(bytes); return stream; } }
四、最终效果
将html转换为word后,我们就可以看到带有 .doc 的效果了!差不多是如下效果
总结
1. 到这基本就结束了,通过简易的几个接口的方式,展示了如何通过将Swagger接口文档生成word文档。可以根据自己的html模板生成各式的word样式文档说明。
2.写这篇番外主要是因为之前介绍了关于如何使用Swagger生成在线文档,但实际工作中,可能也会遇到这种要各种正式word文档的客户,所以在此分享一些想法和思路,同时希望大家不吝指教。
如果觉得《idea swagger生成接口文档_.NetCore3.1中使用Swagger生成接口文档》对你有帮助,请点赞、收藏,并留下你的观点哦!