失眠网 > idea swagger生成接口文档_.NetCore3.1中使用Swagger生成接口文档

idea swagger生成接口文档_.NetCore3.1中使用Swagger生成接口文档

时间：2023-06-17 12:57:18

前言

本来在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; } }