前言

回顾之前的两篇Swagger做Api接口文档，我们大体上学会了如何在net core3.1的项目基础上，搭建一套自动生产API接口说明文档的框架。

本来在Swagger的基础上，前后端开发人员在开发生产期间，可以借此进行更加便捷的沟通交流。可是总有些时候，遇到一些难缠的，又不讲道理，偏偏觉得将Swagger文档地址丢给客户会不够正式！死活要一份word文档。

可是这个时候，如果接口数量上百个，甚至更多，一个一个手动输入word，那将是一笔耗时的工作。但却有什么办法可以解决呢？

对了，利用Swagge生成的Json文件转换为word文档不就可以了吗？

思路

1. 获取Swagger接口文档的Json文件

2. 解析Json文件数据填充到Html的表格中

3.根据生成的html转work文档

模板

文档模板


URL	/api/Movie/AddMovie
请求方式	Post
参数名	参数类型	是否必填	说明
id	Query	False	影视ID
Name	Query	False	电影名称
Type	Query	False	电影类型
状态码	说明
200	Success
示例
请求参数
返回值

开始

一、根据Swagger版本获取Json数据

1.通过Swagger源码文件可以看到

可以拿到swagger生成的文档数据，所以我们可以新建一个控制器SwaggerController.cs,

        private readonly SwaggerGenerator _swaggerGenerator;

        public SwaggerController(SwaggerGenerator swaggerGenerator)

        {

            _swaggerGenerator = swaggerGenerator;

        }

        /// <summary>

        /// 导出文件

        /// </summary>

        /// <param name="type">文件类型</param>

        /// <param name="version">版本号V1</param>

        /// <returns></returns>

        [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>(); //注入SwaggerGenerator,后面可以直接使用这个方法

二、文件数据填充到Html的表格中

根据上面获取的model文件数据，这个时候，我们利用Razor文件，结合html的table模板，将数据遍历填充到页面中，生成完整的页面

Html模板

@using Swashbuckle.AspNetCore.Swagger;

<!DOCTYPE html>

<html>

<head>

    <title>Swagger API文档代码文件</title>

    <style type='text/css'>

        table, table td, table th {

            border: 1px solid #000000;

            border-collapse: collapse;

        }

        table {

            table-layout: fixed;

            word-break: break-all;

        }

        tr {

            height: 20px;

            font-size: 12px;

        }

    </style>

</head>

<body>

    <div style='width:1000px; margin: 0 auto'>

        <span><i>Word接口文档</i></span>

        <h1 align="center">@Model.Info.Title</h1>

        <h1 align="center">接口文档 @Model.Info.Version</h1>

        <h4>联系方式</h4>

        <span>作者：@Model.Info.Contact.Name</span>

        <br>

        <a href="mailto:@Model.Info.Contact.Email" rel="noopener noreferrer" class="link">Send email to Xunit.Core</a>

        <br>

        <a href="@Model.Info.Contact.Url" target="_blank" rel="noopener noreferrer" class="link">@Model.Info.Contact.Name - Website</a>

        <br>

        <h3>接口描述</h3>

        <span>@Model.Info.Description</span>

        <br>

        <table border='1' cellspacing='0' cellpadding='0' style="table-layout: fixed; word-break: break-all;border: 1px solid #000000;border-collapse: collapse;" width='100%'>

            <tr style="border: 1px solid #000000;border-collapse: collapse;">

                <td align="center" style="background-color: rgb(84, 127, 177);">说明</td>

                <td></td>

            </tr>

            <tr style="border: 1px solid #000000;border-collapse: collapse;">

                <td align="center" style="background-color: rgb(84, 127, 177);">类型</td>

                <td></td>

            </tr>

        </table>

        @foreach (var item in Model.Paths)

        {

            if (item.Value.Operations != null)

            {

                foreach (var operation in item.Value.Operations)

                {

                    <h3>@operation.Value.Summary</h3>

                    <table border='1' cellspacing='0' cellpadding='0' width='100%' style="table-layout: fixed; word-break: break-all;border: 1px solid #000000;border-collapse: collapse;">

                        <tr style="background-color: rgb(84, 127, 177);" align="center">

                            <td colspan='5'></td>

                        </tr>

                        <tr style="border: 1px solid #000000;border-collapse: collapse;">

                            <td style="border: 1px solid #000000;border-collapse: collapse;">URL</td>

                            <td colspan='4'>@item.Key</td>

                        </tr>

                        <tr style="border: 1px solid #000000;border-collapse: collapse;">

                            <td style="border: 1px solid #000000;border-collapse: collapse;">请求方式</td>

                            <td colspan='4'>

                                @operation.Key

                            </td>

                        </tr>

                        @if (operation.Value.Parameters != null && operation.Value.Parameters.Count > 0)

                        {

                            <tr style="background-color: rgb(84, 127, 177);" align='center'>

                                <td style="border: 1px solid #000000;border-collapse: collapse;">参数名</td>

                                <td style="border: 1px solid #000000;border-collapse: collapse;">参数类型</td>

                                <td style="border: 1px solid #000000;border-collapse: collapse;">是否必填</td>

                                <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='2'>说明</td>

                            </tr>

                            @foreach (var param in operation.Value.Parameters)

                            {

                                <tr align='center' style="border: 1px solid #000000;border-collapse: collapse;">

                                    <td style="border: 1px solid #000000;border-collapse: collapse;">@param.Name</td>

                                    <td style="border: 1px solid #000000;border-collapse: collapse;">@param.In</td>

                                    <td style="border: 1px solid #000000;border-collapse: collapse;">@param.Required</td>

                                    <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='2'>@param.Description</td>

                                </tr>

                            }

                        }

                        <tr style="background-color: rgb(84, 127, 177);" align='center'>

                            <td style="border: 1px solid #000000;border-collapse: collapse;">状态码</td>

                            <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='4'>说明</td>

                        </tr>

                        @if (operation.Value.Responses != null && operation.Value.Responses.Count > 0)

                        {

                            foreach (var response in operation.Value.Responses)

                            {

                                <tr align='center' style="border: 1px solid #000000;border-collapse: collapse;">

                                    <td style="border: 1px solid #000000;border-collapse: collapse;">@response.Key</td>

                                    <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='4'>@response.Value.Description</td>

                                </tr>

                            }

                        }

                        <tr style="background-color: rgb(84, 127, 177);">

                            <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='5'>示例</td>

                        </tr>

                        <tr style="height: 40px;" style="border: 1px solid #000000;border-collapse: collapse;">

                            <td style="background-color: rgb(84, 127, 177);">请求参数</td>

                            <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='4'></td>

                        </tr>

                        <tr style="height: 40px;" style="border: 1px solid #000000;border-collapse: collapse;">

                            <td style="background-color: rgb(84, 127, 177);">返回值</td>

                            <td style="border: 1px solid #000000;border-collapse: collapse;" colspan='4'></td>

                        </tr>

                    </table>

                    <br>

                }

            }

        }

    </div>

</body>

</html>

将数据遍历到静态页面中，

        /// <summary>

        /// 将数据遍历静态页面中

        /// </summary>

        /// <param name="templatePath">静态页面地址</param>

        /// <param name="model">获取到的文件数据</param>

        /// <returns></returns>

        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文档

        /// <summary>

        /// 静态页面转文件

        /// </summary>

        /// <param name="html">静态页面html</param>

        /// <param name="type">文件类型</param>

        /// <param name="contenttype">上下文类型</param>

        /// <returns></returns>

        public Stream SwaggerConversHtml(string html, string type, out string contenttype)

        {

            string fileName = Guid.NewGuid().ToString() + type;

            //文件存放路径

            string webRootPath = _hostingEnvironment.WebRootPath;

            string path = webRootPath + @"\Files\TempFiles\";

            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);

                //保存为Word

                document.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, , bytes.Length);

            // 设置当前流的位置为流的开始

            stream.Seek(, 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文档的客户，所以在此分享一些想法和思路，同时希望大家不吝指教。

3.后续还会不断修改和完善，可以更多的生成不同的文件类型和按需生成不同版本的接口文档，持续更新。。。

4 .注：搜索关注公众号【DotNet技术谷】--回复【文档生成器】，可获取本篇Swagger转换work文件

5. 参考资料：Spire.Doc文件、Swagger开源地址

6.源码下载

基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (番外篇)的更多相关文章

基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (补充篇)
前言在上一篇导出文档番外篇中,我们已经熟悉了怎样根据json数据导出word的文档,生成接口文档,而在这一篇,将对上一篇进行完善补充,增加多种导出方式,实现更加完善的导出功能. 回顾 1. 获取Sw ...
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (上篇)
前言为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)
前言回顾上一篇文章<使用Swagger做Api文档 >,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终 ...
JavaWeb项目中集成Swagger API文档
1.增加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-sw ...
ABP框架搭建项目系列教程基础版完结篇
返回总目录<一步一步使用ABP框架搭建正式项目系列教程> 经过前面十二篇的基础教程,现在终于该做个总结了. 回顾第一篇,我们建议新手朋友们先通过ABP官网的启动模板生成解决方案,因为这样 ...
分享一个集成在项目中的REST APIs文档框架swagger
1 为什么是使用swagger? 1-1 当后台开发人员开发好接口,是不是还要重新书写一份接口文档提给前端人员,当然对于程序员最不喜欢的就是书写文档(当然文档是必须的,有利于项目的维护) 1-2 当后 ...
使用Swagger 搭建高可读性ASP.Net WebApi文档
一.前言在最近一个商城项目中,使用WebApi搭建API项目.但开发过程中,前后端工程师对于沟通接口的使用,是非常耗时的.之前也有用过Swagger构建WebApi文档,但是API文档的可读性并不高 ...
springboot+swagger接口文档企业实践（上）
目录 1.引言 2.swagger简介 2.1 swagger 介绍 2.2 springfox.swagger与springboot 3. 使用springboot+swagger构建接口文档 3. ...
Spring系列(零) Spring Framework 文档中文翻译
Spring 框架文档(核心篇1和2) Version 5.1.3.RELEASE 最新的, 更新的笔记, 支持的版本和其他主题,独立的发布版本等, 是在Github Wiki 项目维护的. 总览历 ...

随机推荐

史上最全Beyond Compare中文文档.CHM （根据官网整理编辑）
截图如下: 下载地址: 链接:https://pan.baidu.com/s/1Ml98_biT1leXxGLr9fqI_w 提取码:p8jg
【布局】圣杯布局&双飞翼布局
背景随着前端技术的发展推进,web端的布局方式已基本成熟,那么在网站布局方式中,三列布局最为常用,布局方式也有很多,渐渐的开发者们开始从效率的角度优化自己的代码"如果三排布局能将中间的模块 ...
js移动端滑倒顶部加载历史消息解决方案!
最近做了一个语音直播聊天的项目,有一个功能是当没有直播时,进入房间可以查看历史消息,滑动到顶部加载之前的历史消息,我用jquery scroll事件,来判断是否滚动到顶部,问题来了: 首先触发请求事件 ...
浏览器渲染流程&Composite（渲染层合并）简单总结
梳理浏览器渲染流程首先简单了解一下浏览器请求.加载.渲染一个页面的大致过程: DNS 查询 TCP 连接 HTTP 请求即响应服务器响应客户端渲染这里主要将客户端渲染展开梳理一下,从浏览器器内 ...
一文快速入门Shell脚本_了解Sheel脚本基本命令
通过代码和注释的形式,列举了shell的基础操作,快速入门.shell在线编辑器注释单行用#号:多行::<<' 多行注释... '.:<<a 多行注释... a.:< ...
Error response:/usr/bin/tf_serving_entrypoint.sh: line 3: 6 Illegal instruction (core dumped) ...
用docker部署tensorflow-serving:gpu时,参照官方文档:https://tensorflow.google.cn/tfx/serving/docker 本应该是很简单的部署,没 ...
内网渗透之跨边界传输 - 反弹shell
大年初一,当然是更一篇重磅文章啦反弹shell /bin目录下带sh的都是shell nc 1.正向连接,目标机监听自身端口,攻击机主动建立连接目标机:nc -lvvp 端口 -e /bin/ba ...
数据挖掘入门系列教程（四点五）之Apriori算法
目录数据挖掘入门系列教程(四点五)之Apriori算法频繁(项集)数据的评判标准 Apriori 算法流程结尾数据挖掘入门系列教程(四点五)之Apriori算法 Apriori(先验)算法关联 ...
某些时候 v-if 会导致 v-modal 内部数据获取不到也watch不到，这个时候用v-show即可，另外提一下数组要整体赋值才有双向绑定
某些时候 v-if 会导致 v-modal 内部数据获取不到也watch不到,这个时候用v-show即可,另外提一下数组要整体赋值才有双向绑定
创建Sphinx + GitHub + ReadtheDocs托管文档
最新博客链接 "Tsanfer's Blog" 创建Sphinx + GitHub + ReadtheDocs托管文档 Readthedocs在线电子书链接

基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (番外篇)

前言

思路

模板