基於.NetCore3.1搭建項目系列 —— 使用Swagger導出文檔 (番外篇)

来源:https://www.cnblogs.com/i3yuan/archive/2020/04/05/12633768.html

前言 回顧之前的兩篇Swagger做Api介面文檔,我們大體上學會瞭如何在net core3.1的項目基礎上,搭建一套自動生產API介面說明文檔的框架。 本來在Swagger的基礎上,前後端開發人員在開發生產期間,可以藉此進行更加便捷的溝通交流。可是總有些時候,遇到一些難纏的,又不講道理,偏偏覺得將 ...


前言

  回顧之前的兩篇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, 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文檔的客戶,所以在此分享一些想法和思路,同時希望大家不吝指教。

  3.後續還會不斷修改和完善,可以更多的生成不同的文件類型和按需生成不同版本的介面文檔,持續更新。。。

  4 .註:搜索關註公眾號【DotNet技術谷】--回覆【文檔生成器】,可獲取本篇Swagger轉換work文件

  5. 參考資料:Spire.Doc文件 、Swagger開源地址

  6.源碼下載


您的分享是我們最大的動力!

更多相關文章
  • 原文: "Java Garbage Collection Algorithms [till Java 9]" 垃圾回收(Garbage collection,GC)一直是 Java 流行背後的重要特性之一。垃圾回收是 Java 中用於釋放未使用記憶體的機制。本質上,它跟蹤所有仍在使用的對象,並將其餘的 ...
  • 前言 AQS一共花了5篇文章,對裡面實現的核心源碼都做了註解 也和大家詳細描述了下,後面的幾篇文字我將和大家聊聊一下AQS的實際使用,主要會聊幾張鎖,第一篇我會和大家聊下ReentrantLock 重入鎖,雖然在講AQS中也穿插了講了一下,但是我還是深入的聊下 ==PS:前面5篇寫在了CSDN裡面 ...
  • SpringCloud版本:Finchley.SR2 SpringBoot版本:2.0.3.RELEASE 源碼地址:https://gitee.com/bingqilinpeishenme/Java Tutorials 前言 寫博客一個多月了,斷斷續續的更新,今天有小伙伴催更新了,很高興,說明我的 ...
  • 前言 最近想起半年前鴿下來的Haskell,重溫了一下忘得精光的語法,讀了幾個示常式序,挺帶感的,於是函數式編程的草就種得更深了。又去Google了一下C++與FP,找到了一份近乎完美的講義,然後被帶到C++20的ranges library,對即將發佈的C++20滿懷憧憬。此時,我猛然間意識到,看 ...
  • ​ 1.問題 1、如何理解類文件結構佈局? 2、如何應用類載入器的工作原理進行將應用輾轉騰挪? 3、熱部署與熱替換有何區別,如何隔離類衝突? 4、JVM如何管理記憶體,有何記憶體淘汰機制? 5、JVM執行引擎的工作機制是什麼? 6、JVM調優應該遵循什麼原則,使用什麼工具? 7、JPDA架構是什麼,如何 ...
  • 原文鏈接:http://www.yiidian.com/hibernate/hibernate get load.html 1 演示get和load方法的基本使用 源碼下載:https://pan.baidu.com/s/1c2HD7tm 2 分析get和load方法的區別 在hibernate中我 ...
  • Consul是HashiCorp公司推出的開源工具,Consul由Go語言開發,部署起來非常容易,只需要極少的可執行程式和配置文件,具有綠色、輕量級的特點。Consul是`分散式`的、`高可用`的、 `可橫向擴展`的用於實現分散式系統的服務發現與配置。 ...
  • 這篇文章中,我將詳細介紹ASP.NET Core OutOfProcess Hosting模型。強烈推薦你去看看我之前寫的ASP.NET Core InProcess以及ASP.NET Core中的 Kestrel Web伺服器。這篇文章我將向大家詳細介紹下麵幾個問題:怎樣在ASP.NET Core... ...
一周排行
  • 一:背景 1. 講故事 如果你常翻看FCL的源碼,你會發現這裡面有不少方法藉助了C/C++的力量讓C#更快更強悍,如下所示: [DllImport("QCall", CharSet = CharSet.Unicode)] [SecurityCritical] [SuppressUnmanagedCo ...
  • 上一篇(https://www.cnblogs.com/meowv/p/12966092.html)文章使用AutoMapper來處理對象與對象之間的映射關係,本篇主要圍繞定時任務和數據抓取相關的知識點並結合實際應用,在定時任務中迴圈處理爬蟲任務抓取數據。 開始之前可以刪掉之前測試用的幾個Hello ...
  • 首先創建實體類 1 public class MacState 2 { 3 /// <summary> 4 /// 請求狀態 5 /// </summary> 6 public string success { get; set; } 7 /// <summary> 8 /// 錯誤信息 9 /// ...
  • 0. 前言 前幾天FreeSql的作者向我推薦了FreeSql框架,想讓我幫忙寫個文章介紹一下。嗯,想不到我也能帶個貨了。哈哈,開個玩笑~看了下覺得設計的挺有意思的,所以就謝了這篇文章。 簡單介紹一下,FreeSql 是NCC組織的沙盒級項目,是一款功能強大的 ORM 組件,支持 .NET Core ...
  • 0. 前言 這是一個新的系列,名字是《ASP.NET Core 入門到實戰》。這個系列主講ASP.NET Core MVC,輔助一些前端的基礎知識(能用來實現我們需要的即可,並非主講)。同時這個系列也會在後續介紹ASP.NET Core 平臺的其它類型的項目,並帶領大家以各個類型的項目為主要架構開發 ...
  • 我寫了一個Winform測試程式,用的System.Timers.Timer,在事件里,設置label1.Text,然後,居然句柄泄漏、用戶對象泄漏! 百思不得其解,最後換成System.Windows.Forms.Timer,居然不泄漏了! 最近睡眠不足,哪怕一個很小的問題,隨便搞搞,都半夜了! ...
  • leetcode-7. 整數反轉。 給出一個 32 位的有符號整數,你需要將這個整數中每位上的數字進行反轉。 示例 1: 輸入: 123 輸出: 321 示例 2: 輸入: -123 輸出: -321 示例 3: 輸入: 120 輸出: 21 註意: 假設環境只能存儲得下 32 位的有符號整數,則其 ...
  • 1. Java 虛擬機是什麼? 1.1 虛擬機 虛擬機:虛擬的電腦,一個用來執行虛擬電腦指令的軟體。 虛擬機分為系統虛擬機和程式虛擬機。 系統虛擬機:提供一個可運行完整操作系統的軟體平臺,如 Visual Box、VMware。 程式虛擬機:專門執行單個程式的,典型代表 Java 虛擬機。Jav ...
  • 前言 - strlen 概述 無意間掃到 glibc strlen.c 中代碼, 久久不能忘懷. 在一無所知的編程生涯中又記起點點滴滴: 編程可不是兒戲 ❀, 有些難, 也有些不捨. 隨軌跡一同重溫, 曾經最熟悉的 strlen 手感吧 ~ /* Copyright (C) 1991-2020 Fr ...
  • 背景 隊列[Queue]:是一種限定僅在表頭進行刪除操作,僅在表尾進行插入操作的線性表;即先進先出(FIFO-first in first out):最先插入的元素最先出來。 本文通過編碼實現鏈式隊列類,並模擬一個有趣的應用,能夠幫助我們對鏈式隊列有更深度的理解。 基本概念 結點 每個元素,除了存儲 ...