Swagger2生成离线文档markdown、html以及pdf格式

第一次写文章，不喜勿喷，谢谢

实现离线文档我们只需要三板斧

1. 第一板斧:导入依赖

<dependency>  
    <groupId>com.github.xiaoymin</groupId>  
      <artifactId>knife4j-spring-ui</artifactId>    
      <version>2.0.3</version>
	</dependency>
	<dependency>    
	<groupId>com.github.xiaoymin</groupId>    
	<artifactId>knife4j-spring-boot-starter</artifactId>   
	 <version>2.0.3</version>
	</dependency>
	<dependency>    
	<groupId>io.github.swagger2markup</groupId>   
	<artifactId>swagger2markup</artifactId>    
	<version>1.3.1</version>
</dependency>

2.第二板斧：导入组件

这里需要特别注意:把当前项目启动所用的端口改为自己的端口号

<build>
    <plugins>
        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.2.0</version>
            <configuration>
                <!--此处端口一定要是当前项目启动所用的端口-->
                <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                <outputDir>src/docs/asciidoc/generated</outputDir>
                <config>
              <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->                    					
              <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                </config>
          </configuration>
  </plugin>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.3</version>
        <!-- Include Asciidoctor PDF for pdf generation -->
        <!--生成PDF-->
        <dependencies>
            <dependency>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctorj-pdf</artifactId>
                <version>1.5.0-alpha.14</version>
            </dependency>
            <!-- Comment this section to use the default jruby artifact provided by the plugin -->
            <dependency>
                <groupId>org.jruby</groupId>
                <artifactId>jruby-complete</artifactId>
                <version>1.7.21</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>
        </plugins>
    </build>

标注:若想生成markdown格式的离线文档把组件中这里的ASCIIDOC改为MARKDOWN即可
ASCIIDOC:生成ASCIIDOC格式文档
MARKDOWN:.生成Markdown格式文档
CONFLUENCE_MARKUP:生成Confluence格式文档

   <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->    
 <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>

3.第三板斧:执行命令

特别注意:在执行命令时需启动项目
打开idea的终端(下方的Terminal)输入以下两条命令

mvn swagger2markup:convertSwagger2markup
mvn generate-resources

第二条命令根据你的项目大小执行时间不等，若你项目大的话耐心等待一下

两条命令都能执行通过的话则成功
若成功后，离线文档则生成在:

HTML格式:

PDF格式

若想生成Markdown格式的文档请看第二板斧中的标注

谢谢大家的浏览!