目錄
Swagger文章彙總
Swagger2Markup簡介
Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，比如：AsciiDoc、Markdown、Confluence。
項目版本說明：
- spring boot 2.0.x
- swagger 2.8.0
swagger2markup代碼方式
第一步：編輯pom.xml增加需要使用的相關依賴和倉庫
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
其中依賴組件，這兩個要注意，在離線開發環境，需要自己手動添加到本地倉庫
<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.0</version>
<scope>compile</scope>
</dependency>
第二步：編寫一個單元測試用例來生成執行生成文檔的代碼
生成AsciiDoc
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
@Test
public void generateAsciiDocs() throws Exception {
// 輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/asciidoc/generated"));
}
}
- 通過Java代碼來生成：只需要修改
withMarkupLanguage屬性來指定不同的格式以及toFolder屬性爲結果指定不同的輸出目錄。
生成markdown
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/markdown/generated"));
生成confluence
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/confluence/generated"));
以上代碼內容很簡單，大致說明幾個關鍵內容：
MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式。除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUPfrom(new URL("http://localhost:8080/v2/api-docs")：指定了生成靜態部署文檔的源頭配置，可以是這樣的URL形式，也可以是符合Swagger規範的String類型或者從文件中讀取的流。如果是對當前使用的Swagger項目，我們通過使用訪問本地Swagger接口的方式，如果是從外部獲取的Swagger文檔配置文件，就可以通過字符串或讀文件的方式toFolder(Paths.get("src/docs/asciidoc/generated")：指定最終生成文件的具體目錄位置
在執行了上面的測試用例之後，我們就能在當前項目的src目錄下獲得如下內容：
AsciiDoc
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
Markdown和Confluence
src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md
可以看到，這種方式在運行之後就生成出了4個不同的靜態文件。
輸出到單個文件
如果不想分割結果文件，也可以通過替換toFolder(Paths.get("src/docs/asciidoc/generated")爲toFile(Paths.get("src/docs/asciidoc/generated/all"))，將轉換結果輸出到一個單一的文件中，這樣可以最終生成html的也是單一的。
swagger2markup插件方式
生成asciidoc或markdown文檔
添加swagger2markup插件
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.3</version>
<configuration>
<swaggerInput>http://localhost:9210/v2/api-docs</swaggerInput>
<!-- 生成asciidoc格式 -->
<outputFile>src/docs/asciidoc/generated/all</outputFile>
<!-- <outputDir>src/docs/asciidoc/generated</outputDir>-->
<!-- 生成markdown格式 -->
<!-- <outputFile>src/docs/markdown/generated/all</outputFile>-->
<config>
<!-- 生成asciidoc格式 -->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!-- 生成markdown格式 -->
<!-- <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
<swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
<swagger2markup.generatedExamplesEnabled>true</swagger2markup.generatedExamplesEnabled>
<swagger2markup.inlineSchemaEnabled>false</swagger2markup.inlineSchemaEnabled>
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
</plugin>
生成asciidoc或markdown文檔
- 運行項目
- 執行swagger2markup插件：maven窗口：指定項目下的Plugins.swagger2markup
相關說明
- swaggerInput：swagger生成的接口json數據文件。
- 輸出：
- outputFile：輸出到單一文件中
- outputDir：輸出到指定文件中
- swagger2markup.markupLanguage：輸出格式
- swagger2markup.outputLanguage：語言類型：如中文（ZH），默認英語（EN）
- swagger2markup.generatedExamplesEnabled：指定是否應該生成HTTP請求和響應示例，默認false
- swagger2markup.inlineSchemaEnabled：是否啓用參數內聯
- swagger2markup.pathsGroupedBy：api排序規則 一般用tags排序
swagger2markup插件配置說明
http://swagger2markup.github.io/swagger2markup/1.3.3/#_swagger2markup_properties
生成HTML文檔
添加asciidoctor插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html5</backend>
<attributes>
<!--導航欄在左-->
<toc>left</toc>
<!--顯示層級數-->
<toclevels>3</toclevels>
<!--自動打數字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
生成HTML文檔
- 生成asciidoc文檔
- 執行插件：maven窗口：指定項目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
相關說明
- sourceDirectory：asciidoc文檔所在目錄
- outputDirectory：HTML的輸出目錄
- backend：類型
生成PDF文檔
添加asciidoctor插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
<backend>pdf</backend>
</configuration>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
</plugin>
生成PDF文檔
- 生成asciidoc文檔
- 執行插件：maven窗口：指定項目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
解決PDF出現亂碼、空白的問題：
-
maven倉庫中的asciidoctorj-pdf jar包，使用壓縮工具打開：
- 進入asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\ 目錄
- fonts：字體文件目錄
- themes：配置文件目錄
-
下載字體：
- 字體下載：https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
- 注：只需下載KaiGenGothicCN-Bold.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf、KaiGenGothicCN-Bold-Italic.ttf 即可
- 將字體文件放入fonts目錄中
-
修改配置
- 進入themes目錄，修改default-theme.yml文件
- 修改以base:font_family屬性值對應的字體文件配置：在font:catalog下。
base: font_family: Noto Serif font: catalog: Noto Serif: normal: KaiGenGothicCN-Regular.ttf bold: KaiGenGothicCN-Bold.ttf italic: KaiGenGothicCN-Regular-Italic.ttf bold_italic: KaiGenGothicCN-Bold-Italic.ttf
同時生成HTML與PDF文檔
添加插件
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
</configuration>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.16</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<attributes>
<!--導航欄在左-->
<toc>left</toc>
<!--顯示層級數-->
<toclevels>3</toclevels>
<!--自動打數字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
同時生成HTML與PDF文檔
- 生成asciidoc文檔
- 執行插件：maven窗口：指定項目下的Plugins.asciidoctor.asciidoctor:process-asciidoc
- 生成文檔（二者選其一）：注：此步驟耗時，大概七八分鐘
- 執行命令mvn generate-resources
- 使用idea設置快捷啓動：run/debug configurations -> maven -> command line:generate-resources，執行
PDFPDF出現亂碼、空白的問題
- 參考單獨生成PDF問題解決
相關說明
- executions：多個執行任務配置
- execution.id：不可重複
- 其他：參考單獨生成HTML與PDF相關說明
參考鏈接：
http://blog.didispace.com/swagger2markup-markdown-confluence/