Swagger2導出Html和pdf文件

​ 開發人員一般最煩的事情就是寫接口文檔，一路走來，我用過的接口文檔的軟件也不少了，最近用的是swagger。當你需要和第三方公司對接，需要導出Html或者pdf時，請仔細看本文檔。

第一步 pom.xml

添加依賴

 <dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>

在 中，添加

<plugins>
            <!--此插件生成ASCIIDOC-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.2.0</version>
                <configuration>
                    <!--此處端口一定要是當前項目啟動所用的端口-->
                    <swaggerInput>http://localhost:8084/</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP可選 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>
            <!--此插件生成HTML和PDF-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.24</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <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>
                        </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>

            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
            </plugin>
            </plugins>

第二步 添加測試類

@RunWith(SpringRunner.class)
public class ExportConfig {

    @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:8084/v2/api-docs")).withConfig(config)
                .build().toFolder(Paths.get("src/docs/asciidoc/generated"));
    }
}

第三步 執行代碼、命令

1、運行第二步添加的測試類的方法

2、若使用的idea，在terminal中執行：mvn asciidoctor:process-asciidoc

3、執行：mvn generate-resources

完畢！！！運行結果在src/docs目錄中可以看到。。

注意

當你看到結果的字體不滿意時，或者出現下圖文件

這個時候你需要在你的maven倉庫中放入jar：