將工程的Swagger匯出成HTML
阿新 • • 發佈:2019-01-14
1.新增相關依賴(除基本的Swagger依賴)
<dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency> <dependency> <groupId>ch.netzwerg</groupId> <artifactId>paleo-core</artifactId> <version>0.10.2</version> </dependency> <dependency> <groupId>io.vavr</groupId> <artifactId>vavr</artifactId> <version>0.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>2.7.0</version> <scope>test</scope> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.6</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.pegdown</groupId> <artifactId>pegdown</artifactId> <version>1.4.2</version> </dependency>
2.新增plugin
<plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--選單欄在左邊--> <toc>left</toc> <!--多標題排列--> <toclevels>3</toclevels> <!--自動打數字序號--> <sectnums>true</sectnums> </attributes> </configuration> </plugin>
3.新增相關程式碼,生成ASCII檔案
@Value("${swagger.application.name}") private String name; @Test public void generateAsciiDocs() throws Exception { // 輸出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/"+name)); } /** * 生成Markdown格式文件 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 輸出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated")); }
然後執行,生成.adoc檔案
以上程式碼內容很簡單,大致說明幾個關鍵內容:
MarkupLanguage.ASCIIDOC:指定了要輸出的最終格式。除了ASCIIDOC之外,還有MARKDOWN和CONFLUENCE_MARKUP
from(new URL("http://localhost:8080/v2/api-docs"):指定了生成靜態部署文件的源頭配置,可以是這樣的URL形式,也可以是符合Swagger規範的String型別或者從檔案中讀取的流。如果是對當前使用的Swagger專案,我們通過使用訪問本地Swagger介面的方式,如果是從外部獲取的Swagger文件配置檔案,就可以通過字串或讀檔案的方式
toFolder(Paths.get("src/docs/asciidoc/generated"):指定最終生成檔案的具體目錄位置
輸出到單個檔案
如果不想分割結果檔案,也可以通過替換toFolder(Paths.get(“src/docs/asciidoc/generated”)為toFile(Paths.get(“src/docs/asciidoc/generated/all”)),將轉換結果輸出到一個單一的檔案中,這樣可以最終生成html的也是單一的。
生成後執行該外掛的asciidoctor:process-asciidoc命令之後,就能在docs/asciidoc/html目錄下生成最終可用的靜態部署HTML了。