整合營銷服務商

          電腦端+手機端+微信端=數據同步管理

          免費咨詢熱線:

          AsciiDoc 的相關整理

          . AsciiDoc 簡介

          • AsciiDoc 是一種文本文檔格式(輕量級的標記語言),用于編寫注釋、文檔、文章、書籍、電子書、幻燈片、網頁、手冊頁和博客。
          • AsciiDoc 文件可以翻譯成多種格式,包括 HTML、PDF、EPUB、手冊頁面等。
          • AsciiDoc 是高度可配置的,用戶可以定制和擴展 AsciiDoc 源文件語法和后端輸出標記(幾乎可以是任何類型的 SGML/XML 標記)。
          • AsciiDoc 是免費軟件,并根據 GNU 通用公共許可證版本 2(GPLV2)的條款進行許可。

          1.1 語法

          1.1.1 文檔頭

          • 可以包含文檔頭、作者、修訂行、自定義屬性等。
          • 頭部可選但是必須在文檔的頂部。
          = My Document's Title
          Doc Writer <doc.writer@asciidoctor.org>
          v1.0, 2018-04-11
          :toc:
          :imagesdir: assets/images
          :homepage: https://asciidoctor.org
          My document provides...
          

          1.1.2 標題

          • 需要靠左側頂格。
          • 可以包含文檔頭、第 1 ~ 第 5 章節標題。
          • 當使用項目文檔類型(默認值)時,只能有一個 0 級的節標題(即,文檔標題),并且它必須位于文檔頭中。
          • 等號的數目與 HTML 輸出中的標題級別相匹配。
          • 例如,(=)轉換成為 <h2> 標簽。
          = 文檔標題 (0級) =
          == 段落標題 (1級) ==
          === 段落標題 (2級) ===
          ==== 段落標題 (3級) ====
          ===== 段落標題 (4級) =====
          

          1.1.3 段落

          • 段落不需要任何特殊的標記,段落只需要是連續文本的一行或多行。
          • 開始新的段落需要用一個空行進行分隔。
          • 文檔中的大部分內容是段落文本,因此 AsciiDoc 不需要任何特殊的標記或屬性來指定段落內容。
          Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.
          To begin a new paragraph, separate it by at least one blank line. Newlines within a paragraph are not displayed.
          

          1.1.3.1 換行

          • 在 AsciiDoc 中,相鄰或連續的文本行形成段落元素。若要在另一個元素(如節標題或表)之后開始新的段落,則插入空行,然后繼續鍵入內容即可。
          • 因為 AsciiDoc 轉換文檔時,相鄰的文本行會被合并為單個段落,這意味著可以包裝段落文本或將每個句子或短語放在單獨的行上,輸出中是不會出現換行的。
          • 如果希望保留段落中的換行符,可以使用加號 (+) 后的空格或 hardbreaks 屬性。這樣會導致每一行之后增加可見的換行標記(例如 <BR>)。
          Rubies are red, +
          Topazes are blue.
          [%hardbreaks]
          Ruby is red.
          Java is black.
          
          • 通過將 hardbreaks 屬性添加到文檔頭部,可以在整個文檔中保留換行符。
          :hardbreaks:
          ......
          Rubies are red,
          Topazes are blue.
          

          1.1.3.2 文字段落

          • 由至少一個空間偏移的段落成為文字段落,文字段落中的所有行必須是相鄰的。
          • 文本段落顯示為預格式化文本,文本以固定寬度字體顯示,空格和換行符都會被保留下來。

          1.1.3.3 提示段落

          • 主要是為了引起讀者注意,用標簽開頭。
          • 標簽必須大寫,后面跟著冒號(:)。

          標簽說明 NOTE 注釋,TIP 提示,WARNING 警告,IMPORTANT 重要,CAUTION 注意。

          TIP: Pro tip...
          IMPORTANT: Don't forget...
          WARNING: Watch out for...
          CAUTION: Ensure that...
          
          • 當想對復雜內容應用警告時,可以將標簽設置為塊上的樣式屬性。
          • 下例是在分隔塊上的屬性列表中設置標簽,標簽必須大寫。
          [IMPORTANT] 
          .Feeding the Werewolves
          ==== 
          While werewolves are hardy community members, keep in mind the following dietary concerns:
          . They are allergic to cinnamon.
          . More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
          . Celery makes them sad.
          ====
          
          • 可以使用 icons 參數制定圖標的路徑。
          [icons="./images/icons/wink.png"]
          NOTE: What lovely war.
          
          • 使用 caption 參數定義警告標題返回的文本信息(在警告圖標設置為可用時 icons 參數必須設置為 icons=None)。
          [icons=None, caption="特殊提示"]
          NOTE: This is my special note.
          
          1.1.3.3.1 圖標
          • AsciiDoc 提供三種顯示圖標的策略。
          • 作為文本
          • 作為圖像
          • 作為從圖標字體中選擇的字符。
          • 使用圖標屬性控制策略。默認行顯示返回的文本。
          • 如果希望使用圖像顯示圖標,可以在文檔頭中將圖標屬性設置為空值。如果正在轉換為 DocBook,或者希望使用一種簡單的方法使 HTML 可以脫機查看,則建議采用此策略。DocBook 工具鏈提供了警告和標注等圖標的圖像,這些圖標可以用自己的自定義圖標替換。如果使用內聯圖標宏,則需要為這些圖標提供圖像。
          • 也可以使用字體圖標設置為 AsciiDoc 圖標,若要使用此特性,需要將圖標文件屬性的值設置為文檔標題中的字體。可以從 Awesome 中獲得更多的字體圖標。這種方式默認情況下需要在線訪問。
          = Document Title
          :icons: font
          ......
          NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
          
          • HTML 格式輸出。
          <div class="admonitionblock note">
          <table>
          <tr>
          <td class="icon">
          <i class="fa icon-note" title="Note"></i>
          </td>
          <td class="content">
          Asciidoctor supports font-based admonition icons, powered by Font Awesome!
          </td>
          </tr>
          </table>
          </div>
          
          • AsciiDoc 中添加了 Awesome 的字體超強樣式表和字體文件的引用。
          <link rel="stylesheet" >
          
          1.1.3.3.2 Unicode 文本圖標
          • 代替圖像或基于字體的圖標,可以通過使用一個小技巧使用 Unicode 文本來表示警告圖標。
          • 如果在文檔上沒有設置圖標屬性,AsciiDoc 輸出一個標識警告類型的文本標簽。此標簽的文本來自 AsciiDoc 屬性。
          • 屬性的名稱是 <類型> 標題,其中 <類型> 是小寫中的警告類型。例如,提示提示的屬性是提示字幕。
          • 可以將一個 Unicode 字形賦值給這個屬性,而不是單詞。
          :tip-caption: 
          [TIP]
          It's possible to use Unicode glyphs as admonition icons.
          
          • HTML 格式輸出。
          <td class="icon">
          <div class="title"></div>
          </td>
          
          1.1.3.3.3 內聯圖標
          • 圖標可以插入到段落內容的任意位置,內嵌宏。
          icon:tags[] ruby, asciidoctor
          
          • HTML 格式輸出。
          <div class="paragraph">
          <p><span class="icon"><i class="fa fa-tags"></i></span> ruby, asciidoctor</p>
          </div>
          
          • 內聯圖標宏和角色語法。
          icon:tags[role="blue"] ruby, asciidoctor
          
          • 圖標大小
          • 默認為 1x
          icon:heart[2x]
          icon:heart[size=2x]
          
          • 圖標旋轉和翻轉
          icon:shield[rotate=90, flip=vertical]
          
          • 鏈接
          icon:download[link="http://rubygems.org/downloads/asciidoctor-1.5.2.gem"]
          

          1.1.3.4 引文段落

          • 將引文樣式應用到任何段落,它將使用更大的字體大小。
          • 自動將引文段落進行樣式化。
          • 可以采用 (.) 的方式設置引文角色和分配到段落上。
          • 當將文檔轉換為 HTML 并使用默認樣式表查看時,前導的第一段將自動樣式化為前導段。
          [.lead]
          This text will be styled as a lead paragraph (i.e., larger font).
          

          1.1.4 塊結構

          • 任何塊都可以有一個標題,位于塊的上方。塊標題是從一個點開始的文本行。

          1.1.4.1 文本塊

          • 文字塊定義為三種方式
          • 用一個或多個空格縮進段落的第一行。
          • 將文字屬性應用于段落或區塊。
          • 使用文字塊定界符(…)。
           error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
           absolutely fatal: operation initiation lost in the dodecahedron of doom
           would you like to die again? y/n
          ....
          Lazarus: Where is the *defensive operations manual*?
          Computer: Calculating ...
          Can not locate object that you are not authorized to know exists.
          Would you like to ask another question?
          Lazarus: Did the werewolves tell you to say that?
          Computer: Calculating ...
          ....
          

          注意:在輸出中,粗體文本格式沒有應用于文本。

          • 當希望整個文本塊是文本,并且不希望縮進時,可在元素的頂部設置文本屬性。
          [literal]
          error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
          absolutely fatal: operation initiation lost in the dodecahedron of doom
          would you like to die again? y/n
          

          1.1.4.2 注釋塊

          • 不會輸出到目標文件。
          • 行注釋
          • 行注釋可用于分割元素,如兩個相鄰列表。
          // A single-line comment.
          
          • 塊注釋
          ////
          CommentBlock
          ////
          
          1.1.4.3 清單塊(列表塊)
          • 用于計算機的輸出和文件列表、可用于程序代碼。
          • 里面特殊字符不替換。
          • 列表塊內容被轉換為 <PRE> 文本。
          • 列表塊中的內容只受特殊字符和標注替換的限制。
          • 列表塊名稱應用于內容的兩種方式。
          • 在元素上設置列表屬性。
          • 包含分隔符列表塊中的內容。
          • 將列表塊名稱應用于元素,例如段落,通過在該元素上設置列表屬性。
          [listing]
          This is an example of a paragraph styled with `listing`.
          Notice that the monospace markup is preserved in the output.
          
          • 包含分隔的列表塊由四個連字符(----)組成的行包圍。
          • 列表塊有利于顯示原始源代碼,尤其是與源代碼和源代碼突出顯示器屬性一起使用時。
          .app.rb
          [source,ruby]
          ----
          require 'sinatra'
          get '/hi' do
           "Hello World!"
          end
          
          • 具有自定義替換語法的列表塊。
          :version: 1.5.6.1
          [source,xml,subs="verbatim,attributes"]
          ----
          <dependency>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoctor-java-integration</artifactId>
           <version>{version}</version>
          </dependency>
          ----
          
          • 滾動支持
          • nowrap 會增加(css 樣式 white-space:nowrap 和 word-wrap: normal)到 <PRE> 元素上。
          [source%nowrap,java]
          ----
          public class ApplicationConfigurationProvider extends HttpConfigurationProvider
          {
           @Override
           public Configuration getConfiguration(ServletContext context)
           {
           return ConfigurationBuilder.begin()
           .addRule()
           .when(Direction.isInbound().and(Path.matches("/{path}")))
           .perform(Log.message(Level.INFO, "Client requested path: {path}"))
           .where("path").matches(".*");
           }
          }
          ----
          
          • 全局強制不換行 ,可以設置 prewrap 屬性。
          :prewrap!:
          
          • 帶標題的列表塊
          .Gemfile.lock
          ----
          GEM
           remote: https://rubygems.org/
           specs:
           asciidoctor (1.5.6.1)
          PLATFORMS
           ruby
          DEPENDENCIES
           asciidoctor (~> 1.5.6.1)
          ----
          
          • 帶標注的代碼塊
          [source,ruby]
          ----
          require 'sinatra' // <1>
          get '/hi' do // <2>
           "Hello World!" // <3>
          end
          ----
          <1> Library import
          <2> URL mapping
          <3> HTTP response body
          
          • 帶不可選擇標注的代碼塊
          ----
          line of code // <1>
          line of code # <2>
          line of code ;; <3>
          ----
          <1> A callout behind a line comment for C-style languages.
          <2> A callout behind a line comment for Ruby, Python, Perl, etc.
          <3> A callout behind a line comment for Clojure.
          
          • 具有不可選標注的 XML 代碼塊
          [source,xml]
          ----
          <section>
           <title>Section Title</title> <!--1-->
          </section>
          ----
          <1> The section title is required.
          
          • 直接引入源文件的代碼塊
          [source,ruby]
          ----
          include::app.rb[]
          ----
          
          • 源文件相對源目錄的代碼塊
          :sourcedir: src/main/java
          [source,java]
          ----
          include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
          ----
          
          • 引入源文件一部分的代碼塊
          [source,ruby,indent=0]
          ----
          include::lib/document.rb[lines=5..10]
          ----
          
          • 無分隔符的代碼塊
          [source,xml]
          <meta name="viewport"
           content="width=device-width, initial-scale=1.0">
          This is normal content.
          
          • 代碼列表塊啟動語法高亮可以在文檔頭中設置。
          • 高亮屬性有 coderay、highlightjs、prettify 和 pygments。
          :source-highlighter: pygments
          

          1.1.4.4 側邊欄塊

          • 有邊框顯示。
          .AsciiDoc history
          ****
          AsciiDoc was first released in Nov 2002 by Stuart Rackham.
          It was designed from the start to be a shorthand syntax
          for producing professional documents like DocBook and LaTeX.
          ****
          

          1.1.4.5 引用文本塊

          • 文本塊左上角顯示一個雙引號圖片。
          ____
          QuoteBlock
          ____
          
          • 負責引用塊
          [quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
          ____
          Four score and seven years ago our fathers brought forth
          on this continent a new nation...
          ____
          [quote, Albert Einstein]
          A person who never made a mistake never tried anything new.
          ____
          A person who never made a mistake never tried anything new.
          ____
          [quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as http://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
          ____
          If you don't know where you are going, any road will get you there.
          ____
          
          • 縮寫塊引用(只有 Asciidoctor 支持)
          "I hold it that a little rebellion now and then is a good thing,
          and as necessary in the political world as storms in the physical."
          -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
          
          • 空引用
          [, James Baldwin]
          ""
          Not everything that is faced can be changed.
          But nothing can be changed until it is faced.
          ""
          

          1.1.4.6 案例文本塊

          • 可以使用 NOTE、TIP、IMPORTANT、WARNING、CAUTION 顯示提示塊。
          ====
          ExampleBlock
          ====
          

          1.1.4.7 混合使用

          .Sample document
          ====
          Here's a sample AsciiDoc document:
          [listing]
          ....
          = Title of Document
          Doc Writer
          :toc:
          This guide provides...
          ....
          The document header is useful, but not required.
          ====
          [NOTE]
          ====
          An admonition block may contain complex content.
          .A list
          - one
          - two
          - three
          Another paragraph.
          ====
          

          1.1.4.8 開放塊

          --
          An open block can be an anonymous container,
          or it can masquerade as any other block.
          --
          [source]
          --
          puts "I'm a source block!"
          --
          

          1.1.5 列表

          1.1.5.1 有序列表

          • 通過在第一個列表之后插入一個空白行和一行注釋,可以將兩個相鄰的列表分開。-
          • 約定使用(//)作為行注釋向其他作者提供一個提示,即它是一個列表分隔符。
          1. 阿拉伯數字標注的列表項目.
          a. 小寫字母標注的列表項目.
          F. 大寫字母標注的列表項目.
          iii) 小寫羅馬數字標注的列表項目.
          IX) 大寫羅馬數字標注的列表項目.
          

          1.1.5.2 無序列表

          - List item.
          * List item.
          ** List item.
          *** List item.
          **** List item.
          ***** List item.
          

          1.1.5.3 自定義列表

          • 字母或數字開始 1-4 個冒號或兩個分號結束。
          Operating Systems::
           Linux:::
           . Fedora
           * Desktop
           . Ubuntu
           * Desktop
           * Server
           BSD:::
           . FreeBSD
           . NetBSD
          Cloud Providers::
           PaaS:::
           . OpenShift
           . CloudBees
           IaaS:::
           . Amazon EC2
           . Rackspace
          

          1.1.5.4 問答列表

          [qanda]
          What is Asciidoctor?::
           An implementation of the AsciiDoc processor in Ruby.
          What is the answer to the Ultimate Question?:: 42
          

          1.1.5.5 復選框列表

          * [*] checked
          * [x] also checked
          * [ ] not checked
          * normal list item
          

          1.1.5.6 單行標記

          first term:: definition of first term
          second term:: definition of second term
          

          1.1.5.7 多行標記

          first term::
          definition of first term
          second term::
          definition of second term
          

          1.1.5.8 專業術語列表

          [glossary]
          術語1::
           解釋1.
          術語2::
           解釋2.
          

          1.1.6 文本格式

          1.1.6.1 粗體

          *bold phrase* & **char**acter**s**
          

          1.1.6.2 斜體

          _italic phrase_ & __char__acter__s__
          

          1.1.6.3 等寬字體

          `monospace phrase` & ``char``acter``s``
          
          • 如果要在等寬字體中用到({name})這樣的格式(需要直譯),那么可以使用(+ 和 +)符號或者轉義符(\)。
          You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name.
          

          1.1.6.4 混合使用

          `*_monospace bold italic phrase_*` & ``**__char__**``acter``**__s__**``
          

          1.1.6.5 標記字體(黃色背景)

          Werewolves are allergic to #cassia cinnamon#.
          

          1.1.6.6 字體縮小

          Did the werewolves read the [.small]##small print##?
          

          1.1.6.7 字體擴大

          [.big]##O##nce upon an infinite loop.
          

          1.1.6.8 刪除線

          We need [.line-through]#ten# make that twenty VMs.
          

          1.1.6.9 下劃線

          Where did all the [.underline]#cores# run off to?
          

          1.1.6.10 上標

          ^super^script phrase
          

          1.1.6.11 下標

          ~sub~script phrase
          

          1.1.6.12 智能引號

          • 如果不希望應用智能引號,可以使用 (\)進行轉義。
          "`double curved quotes`"
          '`single curved quotes`'
          Olaf's desk was a mess.
          All of the werewolves`' desks were a mess.
          Olaf had been with the company since the `'60s.
          “double curved quotes”
          ‘single curved quotes’
          Olaf’s desk was a mess.
          All of the werewolves’ desks were a mess.
          Olaf had been with the company since the ’60s.
          

          1.1.6.13 文本替換

          符號顯示說明(C)?版權(TM)?商標(R)?注冊商標…?...省略號->→右箭頭<-←左箭頭=>?右雙箭頭<=?左雙箭頭??數字--—破折號(只能在兩個字符之間使用)

          • 文本替換是指其字符的通用字符集 / Unicode 代碼,使用格式。
          • https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references 可查詢通用字符集。
          hhhh;
          

          1.1.7 其他標簽

          1.1.7.1 文件包含語句

          • 如果不在相鄰的文件包含語句之間插入空白行以保持內容分離,務必在源文檔中添加空白行,以避免意外的結果,如吞并部分標題等。
          = Reference Documentation
          Lead Developer
          This is documentation for project X.
          include::basics.adoc[]
          include::installation.adoc[]
          include::example.adoc[]
          
          • 包含 URL 文件
          include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
          

          1.1.7.2 水平線

          '''
          

          1.1.7.3 分頁符

          <<<
          

          1.1.7.4 超鏈接

          • 外部鏈接
          https://asciidoctor.org - automatic!
          https://asciidoctor.org[Asciidoctor]
          https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
          
          • 具有空格和特殊字符
          link:++https://example.org/?q=[a b]++[URL with special characters]
          link:https://example.org/?q=%5Ba%20b%5D[URL with special characters]
          
          • Windows 路徑
          link:\\server\share\whitepaper.pdf[Whitepaper]
          
          • 相對路徑
          link:index.html[Docs]
          
          • 電子郵件和 IRC
          devel@discuss.arquillian.org
          mailto:devel@discuss.arquillian.org[Discuss Arquillian]
          mailto:devel-join@discuss.arquillian.org[Subscribe, Subscribe me, I want to join!]
          irc://irc.freenode.org/#fedora
          

          1.1.7.5 錨點

          錨點:[[A88]]
          鏈接:<<A88,chapter titles>>
          

          1.1.7.6 圖片

          • 塊圖像
          image::sunset.jpg[]
          image::sunset.jpg[Sunset]
          .A mountain sunset
          [#img-sunset]
          [caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
          image::sunset.jpg[Sunset,300,200]
          image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
          
          • 內聯圖
          Click image:icons/play.png[Play, title="Play"] to get the party started.
          Click image:icons/pause.png[title="Pause"] when you need a break.
          
          • 具有定位角色的內聯圖
          image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
          

          1.1.7.7 視頻

          • 塊視頻
          video::video_file.mp4[]
          video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
          

          1.1.7.8 源碼

          • 內聯方式(等寬字體)
          Reference code like `types` or `methods` inline.
          
          • 內聯方式(直譯方法)
          Output literal monospace text such as `+{backtick}+` by
          enclosing the text in pluses, then again in backticks.
          

          1.1.7.9 文檔目錄(ToC)

          = AsciiDoc Writer's Guide
          Doc Writer <doc.writer@asciidoctor.org>
          v1.0, 2013-08-01
          :toc: right
          

          1.1.7.10 參考文獻

          _The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
          To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.
          [bibliography]
          == References
          - [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
           From Journeyman to Master. Addison-Wesley. 1999.
          - [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
           Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
          

          1.1.7.11 腳注

          A statement.footnote:[Clarification about this statement.]
          A bold statement!footnoteref:[disclaimer,Opinions are my own.]
          Another bold statement.footnoteref:[disclaimer]
          

          1.1.8 表格

          • 除非指定了 cols 屬性,否則列的數量等于塊分隔符之間的第一行(非空)上的單元格分隔符字符的數量。
          • 當空白行跟隨第一個非空行時,第一行中的單元格將升遷到表標題。
          .Table Title
          |===
          |Name of Column 1 |Name of Column 2 |Name of Column 3 
          |Cell in column 1, row 1
          |Cell in column 2, row 1
          |Cell in column 3, row 1
          |Cell in column 1, row 2
          |Cell in column 2, row 2
          |Cell in column 3, row 2
          |===
          
          • cols 屬性中的(*)是重復運算符,意味著在列的其余部分重復列規范。
          • 當頭中的單元格沒有在一行上定義時,必須使用 cols 屬性設置表中的列數,使用 %header 選項(或 .=header 屬性)將第一行提升到表頭。
          [%header,cols=2*] 
          |===
          |Name of Column 1
          |Name of Column 2
          |Cell in column 1, row 1
          |Cell in column 2, row 1
          |Cell in column 1, row 2
          |Cell in column 2, row 2
          |===
          
          • 下例中指定該表有三列,并設置它們的相對寬度。
          [cols="1,1,2", options="header"] 
          .Applications
          |===
          |Name
          |Category
          |Description
          |Firefox
          |Browser
          |Mozilla Firefox is an open-source web browser.
          It's designed for standards compliance,
          performance, portability.
          |Arquillian
          |Testing
          |An innovative and highly extensible testing platform.
          Empowers developers to easily create real, automated tests.
          |===
          
          • 包含其他標簽的表
          [cols="2,2,5a"]
          |===
          |Firefox
          |Browser
          |Mozilla Firefox is an open-source web browser.
          It's designed for:
          * standards compliance
          * performance
          * portability
          http://getfirefox.com[Get Firefox]!
          |===
          
          • CSV 格式的表
          [%header,format=csv]
          |===
          Artist,Track,Genre
          Baauer,Harlem Shake,Hip Hop
          The Lumineers,Ho Hey,Folk Rock
          |===
          
          • CSV 格式速記表(只有 Asciidoctor 支持)
          ,===
          Artist,Track,Genre
          Baauer,Harlem Shake,Hip Hop
          ,===
          
          • 引入 CSV 文件表
          |===
          include::customers.csv[]
          |===
          
          • DSV 數據使用速記表
          :===
          Artist:Track:Genre
          Robyn:Indestructable:Dance
          :===
          
          • 帶格式化、對齊和合并單元的表
          [cols="e,m,^,>s", width="25%"]
          |===
          |1 >s|2 |3 |4
          ^|5 2.2+^.^|6 .3+<.>m|7
          ^|8
          |9 2+>|10
          |===
          

          1.1.9 屬性

          • 定義和使用
          :url-home: https://asciidoctor.org
          :link-docs: https://asciidoctor.org/docs[documentation]
          :summary: Asciidoctor is a mature, plain-text document format for \
           writing notes, articles, documentation, books, and more. \
           It's also a text processor & toolchain for translating \
           documents into various output formats (i.e., backends), \
           including HTML, DocBook, PDF and ePub.
          :checkedbox: pass:normal[{startsb}?{endsb}]
          Check out {url-home}[Asciidoctor]!
          {summary}
          Be sure to read the {link-docs} too!
          {checkedbox} That's done!
          
          • 計數器屬性
          [caption=""]
          .Parts{counter2:index:0}
          |===
          |Part Id |Description
          |PX-{counter:index}
          |Description of PX-{index}
          |PX-{counter:index}
          |Description of PX-{index}
          |===
          

          1.1.10 直譯方式

          • 轉移符直譯
          \*Stars* is not rendered as bold text.
          The asterisks around the word are preserved.
          \{author} is not resolved to the author name.
          The curly brackets around the word are preserved.
          `A\--Z` connects A to Z in monospace using two dashes.
          The dashes are not replaced by an em dash.
          \[[Word]] is not interpreted as an anchor.
          The double brackets around the word are preserved.
          [\[[Word]]] is not interpreted as a bibliography anchor.
          The triple brackets around the word are preserved.
          In these cases, the backslash character is automatically removed.
          
          • (+)號直譯
          `+Text inside {plus} characters+` is not formatted.
          However, special characters like +<+ and +>+ are still escaped.
          
          • pass 宏直譯
          pass:[<u>underline me</u>] is also underlined.
          
          • 三(+)直譯
          +++<u>underline me</u>+++ is underlined.
          

          1.2 兼容 Markdown

          • 兼容 Markdown 標題
          # Document Title (Level 0)
          ## Section Level 1
          ### Section Level 2
          #### Section Level 3
          ##### Section Level 4
          ###### Section Level 5
          
          • 兼容 Markdown 代碼塊
          ```ruby
          require 'sinatra'
          get '/hi' do
           "Hello World!"
          end
          \``` \\ 去除第一個 \ 符號
          
          • 兼容 Markdown 引用塊
          > I hold it that a little rebellion now and then is a good thing,
          > and as necessary in the political world as storms in the physical.
          > -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
          
          • 兼容 Markdown 引用塊和塊內容
          > > What's new?
          >
          > I've got Markdown in my AsciiDoc!
          >
          > > Like what?
          >
          > * Blockquotes
          > * Headings
          > * Fenced code blocks
          >
          > > Is there more?
          >
          > Yep. AsciiDoc and Markdown share a lot of common syntax already.
          
          • 兼容 Markdown 水平線
          ---
          - - -
          ***
          * * *
          

          參考資料

          https://asciidoctor.org/docs/

          近經常被問 https://t.itmuch.com/doc.html 文檔頁是怎么制作的,考慮到步驟略復雜,寫篇手記總結下吧。

          TIPS

          https://t.itmuch.com/doc.html 是個人在慕課網視頻《 面向未來微服務:Spring Cloud Alibaba從入門到進階[1] 》的實戰項目配套文檔。

          效果

          總體步驟

          ?整合Swagger,生成Swagger描述端點 /v2/api-docs

          ?使用 swagger2markup-maven-plugin ,將 /v2/api-docs 生成ASCIIDOC文件;

          ?使用 asciidoctor-maven-plugin ,將ASCIIDOC文件轉換成HTML;

          ?部署

          整合Swagger

          TIPS

          Swagger的使用非常簡單,本文不展開探討了,各位看官自行百度一下用法吧。

          常用注解:

          ?@Api

          ?@ApiOperation

          ?@ApiModel

          ?@ApiModelProperty

          1 加依賴

          <!-- swagger -->
          <!-- 之所以要排除,是因為如果不排除會報NumberFormatException的警告。 -->
          <!-- 參考:https://github.com/springfox/springfox/issues/2265-->
          <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.9.2</version>
           <exclusions>
           <exclusion>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-annotations</artifactId>
           </exclusion>
           <exclusion>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-models</artifactId>
           </exclusion>
           </exclusions>
          </dependency>
          <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.9.2</version>
          </dependency>
          <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-annotations</artifactId>
           <version>1.5.21</version>
          </dependency>
          <dependency>
           <groupId>io.swagger</groupId>
           <artifactId>swagger-models</artifactId>
           <version>1.5.21</version>
          </dependency>
          

          2 配置Swagger(按照自己的需要配置,下面的配置代碼僅供參考)

          /**
           * @author itmuch.com
           */
          @Configuration
          @EnableSwagger2
          public class SwaggerConfiguration {
           /**
           * swagger 信息
           *
           * @return 頁面信息
           */
           private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
           .title("ITMuch API")
           .description("ITMuch API")
           .termsOfServiceUrl("")
           .version("1.0.0")
           .contact(new Contact("", "", "")).build();
           }
           @Bean
           public Docket customImplementation() {
           return new Docket(DocumentationType.SWAGGER_2)
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.itmuch"))
           .paths(PathSelectors.any())
           .build()
           .apiInfo(this.apiInfo());
           //.globalOperationParameters(parameters);
           }
          }
          

          3 為接口Swagger注解

          @RestController
          @RequestMapping("/notices")
          @RequiredArgsConstructor(onConstructor = @__(@Autowired))
          @Api(tags = "公告相關接口", description = "公告相關接口")
          public class NoticeController {
           /**
           * 查詢最新的一條公告
           *
           * @return 公告列表
           */
           @GetMapping("/newest")
           @ApiOperation(value = "查詢最新的一條公告", notes = "用于:公告")
           public Notice findNewest() {
           return new Notice();
           }
          }
          @AllArgsConstructor
          @NoArgsConstructor
          @Builder
          @Data
          @ApiModel("公告")
          public class Notice {
           /**
           * ID
           */
           @ApiModelProperty("id")
           private Integer id;
           /**
           * 公告內容
           */
           @ApiModelProperty("公告內容")
           private String content;
           ...
          }
          

          這樣,應用啟動完成后,就會有一個/v2/api-docs 端點,描述了你的API的信息。

          生成ASCIIDOC

          在pom.xml中添加如下內容:

          <build>
           <plugins>
           <plugin>
           <groupId>io.github.swagger2markup</groupId>
           <artifactId>swagger2markup-maven-plugin</artifactId>
           <version>1.3.1</version>
           <configuration>
           <!-- api-docs訪問url -->
           <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
           <!-- 生成為單個文檔,輸出路徑 -->
           <outputFile>src/docs/asciidoc/generated/all</outputFile>
           <config>
           <!-- ascii格式文檔 -->
           <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
           <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
           </config>
           </configuration>
           </plugin>
           ...
          

          swagger2markup-maven-plugin 插件的作用是讀取 http://localhost:8080/v2/api-docs 的信息,生成ASCIIDOC文檔。當然你也可以生成其他格式,比如Markdown等等。

          這款插件還有很多使用姿勢,詳見 https://github.com/Swagger2Markup/swagger2markup-maven-plugin[2]

          生成HTML

          下面,只需要將ASCIIDOC轉換成html就OK了,在pom.xml中添加如下內容:

          <build>
           <plugins>
           <plugin>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoctor-maven-plugin</artifactId>
           <version>1.5.6</version>
           <configuration>
           <!-- asciidoc文檔輸入路徑 -->
           <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
           <!-- html文檔輸出路徑 -->
           <outputDirectory>src/docs/asciidoc/html</outputDirectory>
           <backend>html</backend>
           <sourceHighlighter>coderay</sourceHighlighter>
           <!-- html文檔格式參數 -->
           <attributes>
           <doctype>book</doctype>
           <toc>left</toc>
           <toclevels>3</toclevels>
           <numbered></numbered>
           <hardbreaks></hardbreaks>
           <sectlinks></sectlinks>
           <sectanchors></sectanchors>
           </attributes>
           </configuration>
           </plugin>
          

          asciidoctor-maven-plugin 插件同樣也有很多姿勢,詳見:https://github.com/asciidoctor/asciidoctor-maven-plugin[3]

          生成的文件在 src/docs/asciidoc/html (看你插件上面的配置哈),然后你就可以弄個NGINX部署了。

          干貨分享

          最近將個人學習筆記整理成冊,使用PDF分享。關注我,回復如下代碼,即可獲得百度盤地址,無套路領取!

          ?001:《Java并發與高并發解決方案》學習筆記;

          ?002:《深入JVM內核——原理、診斷與優化》學習筆記;

          ?003:《Java面試寶典》

          ?004:《Docker開源書》

          ?005:《Kubernetes開源書》

          ?006:《DDD速成(領域驅動設計速成)》


          References

          [1] 面向未來微服務:Spring Cloud Alibaba從入門到進階: https://coding.imooc.com/class/358.html

          [2]: https://github.com/Swagger2Markup/swagger2markup-maven-plugin

          [3]: https://github.com/asciidoctor/asciidoctor-maven-plugin

          相信很多后端開發在項目中都會碰到要寫 api 文檔,不管是給前端、移動端等提供更好的對接,還是以后為了以后交接方便,都會要求寫 api 文檔。

          而手寫 api 文檔的話有諸多痛點:

          • 文檔更新的時候,需要再次發送給對接人
          • 接口太多,手寫文檔很難管理
          • 接口返回的結果不明確
          • 不能直接在線測試接口,通常需要使用工具,如 postman 等

          Swagger 就很好地解決了這個問題。

          Swagger 簡介

          Swagger 是一個規范和完整的框架,用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法,參數和模型緊密集成到服務器端的代碼,允許API來始終保持同步。

          Swagger 使用

          1.相關依賴

          <!--swagger2 -->
                  <dependency>
                      <groupId>io.springfox</groupId>
                      <artifactId>springfox-swagger2</artifactId>
                      <version>2.9.2</version>
                  </dependency>
                  <dependency>
                      <groupId>io.springfox</groupId>
                      <artifactId>springfox-swagger-ui</artifactId>
                      <version>2.9.2</version>
                  </dependency>
          
          

          2.Swagger 配置類

          @Configuration
          @EnableSwagger2
          public class SwaggerConfig {
              @Bean
              public Docket buildDocket() {
                  return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(buildApiInf()) //將api的元信息設置為包含在json resourcelisting響應中
                  //.host("127.0.0.1:8080") //設置ip和端口,或者域名
                  .select()  //啟動用于api選擇的生成器
                  //.apis(RequestHandlerSelectors.any())
                  .apis(RequestHandlerSelectors.basePackage("cn.zwqh.springboot.controller"))//指定controller路徑
                  .paths(PathSelectors.any()).build();
              }
          
              private ApiInfo buildApiInf() {
          
                  Contact contact=new Contact("朝霧輕寒","https://www.zwqh.top/","zwqh@clover1314.com");
                  return new ApiInfoBuilder()
                  .title("Swagger Demo Restful API Docs")//文檔標題
                  .description("Swagger 示例 Restful Api 文檔")//文檔描述
                  .contact(contact)//聯系人
                  .version("1.0")//版本號
                  //.license("")//更新此API的許可證信息
                  //.licenseUrl("")//更新此API的許可證Url
                  //.termsOfServiceUrl("")//更新服務條款URL
                  .build();
          
              }
          }
          

          3.Spring MVC 相關配置

          @Configuration
          public class WebMvcConfig extends WebMvcConfigurationSupport {
              /**
               * 靜態資源配置(默認)
               */
              @Override
              public void addResourceHandlers(ResourceHandlerRegistry registry) {
                  registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 靜態資源路徑
                  registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
                  registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
                  super.addResourceHandlers(registry);
              }
          
          }
          

          如果不添加此靜態資源配置會報錯,找不到相關路徑

          4.Model 中使用 Swagger 注解

          @ApiModel(value = "UserEntity", description = "用戶對象")
          public class UserEntity implements Serializable{
          
              /**
               * 
               */
              private static final long serialVersionUID = 5237730257103305078L;
              @ApiModelProperty(value ="用戶id",name="id",dataType="Long",required = false,example = "1",hidden = false )
              private Long id;
              @ApiModelProperty(value ="用戶名",name="userName",dataType="String",required = false,example = "關羽" )
              private String userName;
              @ApiModelProperty(value ="用戶性別",name="userSex",dataType="String",required = false,example = "男" )
              private String userSex;
          
              public Long getId() {
                  return id;
              }
          
              public void setId(Long id) {
                  this.id = id;
              }
          
              public String getUserName() {
                  return userName;
              }
          
              public void setUserName(String userName) {
                  this.userName = userName;
              }
          
              public String getUserSex() {
                  return userSex;
              }
          
              public void setUserSex(String userSex) {
                  this.userSex = userSex;
              }
          
          }
          
          

          5. Controller 中使用 Swagger 注解

          
          @RestController
          @RequestMapping("/api")
          @Api(tags = { "接口分組1", "接口分組2" })
          public class ApiController {
          
              @Autowired
              private UserDao userDao;
          
              @GetMapping("/getAllUser")
              @ApiOperation(value = "獲取所有用戶", notes = "", httpMethod = "GET", tags = "接口分組3")
              public List<UserEntity> getAll() {
                  return userDao.getAll();
              }
          
              @GetMapping("/getUserById")
              @ApiOperation(value = "根據id獲取用戶", notes = "id必傳", httpMethod = "GET")
              @ApiImplicitParam(name = "id", value = "用戶id",example = "1", required = true, dataType = "long", paramType = "query")
              public UserEntity getOne(Long id) {
                  return userDao.getOne(id);
              }
          
              @PostMapping("/getUserByNameAndSex")
              @ApiOperation(value = "根據name和sex獲取用戶", notes = "", httpMethod = "POST")
              @ApiImplicitParams({
                      @ApiImplicitParam(name = "userName", value = "用戶名", example = "關羽", required = true, dataType = "string", paramType = "query"),
                      @ApiImplicitParam(name = "userSex", value = "用戶性別", example = "男", required = true, dataType = "string", paramType = "query") })
              public UserEntity getUserByNameAndSex(String userName, String userSex) {
                  return userDao.getUserByNameAndSex(userName, userSex);
              }
          
              @PostMapping("/insertUser")
              @ApiOperation(value = "新增用戶", notes = "傳json,數據放body", httpMethod = "POST")
              @ApiImplicitParams({
                      @ApiImplicitParam(name = "body", value = "用戶對象json", example = "{userName:'朝霧輕寒',userSex:'男'}", required = true) })
              public String insertUser(@RequestBody String body) {
                  System.out.println(body);
                  UserEntity user = JSON.parseObject(body, UserEntity.class);
                  userDao.insertUser(user);
                  return "{code:0,msg:'success'}";
              }
          
              @PostMapping("/updateUser")
              @ApiOperation(value = "修改用戶", notes = "傳json,數據放body", httpMethod = "POST")
              @ApiImplicitParams({
                      @ApiImplicitParam(name = "body", value = "用戶對象json", example = "{id:23,userName:'朝霧輕寒',userSex:'女'}", required = true) })
              public String updateUser(@RequestBody String body) {
                  System.out.println(body);
                  UserEntity user = JSON.parseObject(body, UserEntity.class);
                  userDao.updateUser(user);
                  return "{code:0,msg:'success'}";
              }
          
              @PostMapping("/deleteUser")
              @ApiOperation(value = "刪除用戶", notes = "id必傳", httpMethod = "POST")
              public String deleteUser(@ApiParam(name = "id", value = "用戶id", required = true) Long id) {
                  userDao.deleteUser(id);
                  return "{code:0,msg:'success'}";
              }
          }
          

          5.測試

          訪問 http://127.0.0.1:8080/swagger-ui.html 進行接口在線測試

          Swagger 常用注解

          1.@Api

          用于類,表示表示這個類是swagger的資源。屬性如下:

          • tags 表示說明,tags如果有多個值,會生成多個列表
          • value 表示說明,可以使用tags替代

          2.@ApiOperation

          用于方法,表示一個http請求的操作。屬性如下:

          • value 用于方法描述
          • notes 用于提示內容
          • tags 用于API文檔控制的標記列表,視情況而用,可以進行獨立分組

          3.@ApiParam

          用于方法、參數、字段說明;表示對參數的添加元數據。

          • name 參數名
          • value 參數說明
          • required 是否必填

          4.@ApiModel

          用于類,表示對類進行說明,用于參數用實體類接受。

          • value 對象名
          • description 描述

          5.@ApiModelProperty

          用于方法、字段,表示對model屬性的說明或者數據操作更改。

          • value 字段說明
          • name 重寫屬性名
          • dataType 重寫屬性數據類型
          • required 是否必填
          • example 舉例說明
          • hidden 隱藏

          6.@ApiIgnore

          用于類、方法、方法參數,表示這個方法或者類被忽略,不在swagger-ui.html上顯示。

          7.@ApiImplicitParam

          用于方法,表示單獨的請求參數。

          • name 參數名
          • value 參數說明
          • dataType 數據類型
          • paramType 參數類型
          • example 舉例說明

          8.@ApiImplicitParams

          用于方法,包含多個 @ApiImplicitParam。

          9.@ApiResponses @ApiResponse

          用于類或者方法,描述操作的可能響應。

          • code 響應的HTTP狀態代碼
          • message 響應附帶的可讀消息

          10.@ResponseHeader

          用于方法,響應頭設置。

          • name 響應頭名稱
          • description 頭描述
          • response 默認響應類 void
          • responseContainer 參考ApiOperation中配置

          Swagger 導出離線 api 文檔

          1.導出 AsciiDocs、Markdown、Confluence 格式文檔

          添加依賴

          <!-- swagger2markup 相關依賴 -->
                  <dependency>
                      <groupId>io.github.swagger2markup</groupId>
                      <artifactId>swagger2markup</artifactId>
                      <version>1.3.3</version>
                  </dependency>
          

          轉換工具類

          public class SwaggerUtils {
          
              private static final String url = "http://127.0.0.1:8080/v2/api-docs";
              /**
               * 生成AsciiDocs格式文檔
               * @throws MalformedURLException
               */
              public static void generateAsciiDocs() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema().build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFolder(Paths.get("./docs/asciidoc/generated"));
              }
              /**
               * 生成AsciiDocs格式文檔,并匯總成一個文件
               * @throws MalformedURLException
               */
              public static void generateAsciiDocsToFile() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema()
                          .build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFile(Paths.get("./docs/asciidoc/generated/all"));
              }
          
              /**
               * 生成Markdown格式文檔
               * @throws MalformedURLException
               */
              public static void generateMarkdownDocs() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema()
                          .build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFolder(Paths.get("./docs/markdown/generated"));
              }
              /**
               * 生成Markdown格式文檔,并匯總成一個文件
               * @throws MalformedURLException
               */
              public static void generateMarkdownDocsToFile() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema()
                          .build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFile(Paths.get("./docs/markdown/generated/all"));
              }
          
              /**
               * 生成Confluence格式文檔
               * @throws MalformedURLException
               */
              public static void generateConfluenceDocs() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema()
                          .build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFolder(Paths.get("./docs/confluence/generated"));
              }
          
              /**
               * 生成Confluence格式文檔,并匯總成一個文件
               * @throws MalformedURLException
               */
              public static void generateConfluenceDocsToFile() throws MalformedURLException {
                  Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                          .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                          .withOutputLanguage(Language.ZH)
                          .withPathsGroupedBy(GroupBy.TAGS)
                          .withGeneratedExamples()
                          .withoutInlineSchema()
                          .build();
          
                  Swagger2MarkupConverter.from(new URL(url))
                          .withConfig(config)
                          .build()
                          .toFile(Paths.get("./docs/confluence/generated/all"));
              }
          
          }
          

          使用測試 Controller

          @RestController
          @RequestMapping("/export")
          @ApiIgnore
          public class ExportController {
          
              @RequestMapping("/ascii")
              public String exportAscii() throws MalformedURLException{
                  SwaggerUtils.generateAsciiDocs();
                  return "success";
              }
          
              @RequestMapping("/asciiToFile")
              public String asciiToFile() throws MalformedURLException{
                  SwaggerUtils.generateAsciiDocsToFile();
                  return "success";
              }
          
              @RequestMapping("/markdown")
              public String exportMarkdown() throws MalformedURLException{
                  SwaggerUtils.generateMarkdownDocs();
                  return "success";
              }
          
              @RequestMapping("/markdownToFile")
              public String exportMarkdownToFile() throws MalformedURLException{
                  SwaggerUtils.generateMarkdownDocsToFile();
                  return "success";
              }
          
              @RequestMapping("/confluence")
              public String confluence() throws MalformedURLException{
                  SwaggerUtils.generateConfluenceDocs();
                  return "success";
              }
          
              @RequestMapping("/confluenceToFile")
              public String confluenceToFile() throws MalformedURLException{
                  SwaggerUtils.generateConfluenceDocsToFile();
                  return "success";
              }
          }
          
          

          2.導出 html、pdf、xml 格式

          添加依賴

          <!--離線文檔 -->
                  <dependency>
                      <groupId>org.springframework.restdocs</groupId>
                      <artifactId>spring-restdocs-mockmvc</artifactId>
                      <scope>test</scope>
                  </dependency>
                  <!--springfox-staticdocs 生成靜態文檔 -->
                  <dependency>
                      <groupId>io.springfox</groupId>
                      <artifactId>springfox-staticdocs</artifactId>
                      <version>2.6.1</version>
                  </dependency>
          
          <build>
                  <pluginManagement>
                      <plugins>
                          <plugin>
                              <groupId>org.springframework.boot</groupId>
                              <artifactId>spring-boot-maven-plugin</artifactId>
                          </plugin>
                          <plugin>
                              <groupId>io.github.swagger2markup</groupId>
                              <artifactId>swagger2markup-maven-plugin</artifactId>
                              <version>1.3.1</version>
                              <configuration>
                                  <swaggerInput>http://127.0.0.1:8080/v2/api-docs</swaggerInput>
                                  <outputDir>./docs/asciidoc/generated</outputDir>
                                  <config>
                                      <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                                  </config>
                              </configuration>
                          </plugin>
                          <plugin>
                              <groupId>org.asciidoctor</groupId>
                              <artifactId>asciidoctor-maven-plugin</artifactId>
                              <version>1.5.3</version>
                              <!-- <version>2.0.0-RC.1</version> -->
                              <!-- Include Asciidoctor PDF for pdf generation -->
                              <dependencies>
                                  <dependency>
                                      <groupId>org.asciidoctor</groupId>
                                      <artifactId>asciidoctorj-pdf</artifactId>
                                      <version>1.5.0-alpha.10.1</version>
                                  </dependency>
                                  <dependency>
                                      <groupId>org.jruby</groupId>
                                      <artifactId>jruby-complete</artifactId>
                                      <version>1.7.21</version>
                                  </dependency>
                              </dependencies>
                              <configuration>
                                  <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
                                  <outputDirectory>./docs/asciidoc/html</outputDirectory> 
                                  <backend>html</backend>
                                  <!-- <outputDirectory>./docs/asciidoc/pdf</outputDirectory> 
                                  <backend>pdf</backend> -->
                                  <headerFooter>true</headerFooter> 
                                  <doctype>book</doctype> 
                                  <sourceHighlighter>coderay</sourceHighlighter>
                                  <attributes>
                                      <!-- 菜單欄在左邊 -->
                                      <toc>left</toc>
                                      <!-- 多標題排列 -->
                                      <toclevels>3</toclevels>
                                      <!-- 自動打數字序號 -->
                                      <sectnums>true</sectnums>
                                  </attributes>
                              </configuration>                    
                          </plugin>
                      </plugins>
                  </pluginManagement>
          
              </build>
          
          

          可以修改此處 html 和 pdf,通過 mvn asciidoctor:process-asciidoc 可以導出相應格式文件

          <outputDirectory>./docs/asciidoc/html</outputDirectory> 
                                  <backend>html</backend>
          

          執行 mvn asciidoctor:process-asciidoc 后再執行 mvn generate-resources,可在 targt/generated-docs 目錄下生成 xml 格式文件


          主站蜘蛛池模板: 麻豆AV天堂一区二区香蕉| 一区二区三区在线免费| 在线播放国产一区二区三区| 亚洲日本一区二区三区| 亚洲高清一区二区三区| 亚洲国产成人久久综合一区77| 久久久久人妻精品一区蜜桃| 国内精品一区二区三区最新| 天天躁日日躁狠狠躁一区| 国产午夜精品一区理论片飘花 | 亚洲一区精品中文字幕| 视频一区二区在线播放| 久久精品一区二区三区AV| 爆乳熟妇一区二区三区霸乳| 亚洲一本一道一区二区三区| 一区二区三区免费视频播放器 | 日韩久久精品一区二区三区| 久久久久人妻一区精品果冻| ...91久久精品一区二区三区| 国产一区麻豆剧传媒果冻精品| 亚洲熟妇无码一区二区三区| 亚洲一区二区三区偷拍女厕| 精品女同一区二区三区在线| 国产主播在线一区| 91精品国产一区二区三区左线| 国产精品亚洲一区二区三区在线| 日本免费一区尤物| 国产日韩精品一区二区在线观看播放| 在线观看亚洲一区二区| 久久人妻av一区二区软件| 亚洲AV无码一区二区三区DV| 国产成人精品无人区一区| 痴汉中文字幕视频一区| 日韩一区二区三区在线精品| 少妇一晚三次一区二区三区| 伊人色综合一区二区三区影院视频| 精品无码av一区二区三区| 无码乱人伦一区二区亚洲| 国产成人精品日本亚洲专一区| 日韩精品无码一区二区三区不卡| 亚洲夜夜欢A∨一区二区三区|