使用springfox-staticdocs生成swagger離線api

因為最近公司部分專案使用swagger來管理線上介面，但在某些場景下需要提供離線的api文件。因此在網上參考了一些部落格以後寫了一個小專案，只需要配置對應的url，既可生成離線的api文件。該專案的優勢在於是一個獨立的專案，不要整合到實際開發專案中。

說明

• 只適用於整合swagger框架的專案
• 確保專案的/v2/api-docs介面可訪問
• 目前離線文件只支援html5格式，如果需要轉化為doc或pdf格式，可以將生成的html5檔案選擇用world文件開啟，然後選擇’另存為’其他格式。（建議採用html格式，效果最好
  ）

專案簡單說明

1.專案結構

該專案只包含了幾個類檔案，結構如下圖所示:

2.pom檔案

如下:

 <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
 
>
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.beauxie</groupId>
    <artifactId>swagger.export</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>


    <properties>
        <snippetsDirectory>
 
${project.build.directory}/generated-snippets</snippetsDirectory>

        <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
    </properties>

    <dependencies>

        <!--springfox-staticdocs 生成靜態文件-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!--Maven通過Maven Surefire Plugin外掛執行單元測試-->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <testFailureIgnore>true</testFailureIgnore>
                </configuration>
            </plugin>
            <!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
            <!--通過Asciidoctor使得asciidoc生成其他的文件格式，例如：PDF 或者HTML5-->
            <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>${asciidoctor.input.directory}</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                        <generated>${generated.asciidoc.directory}</generated>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                   separate executions for each desired output type -->
                <!--因為每次執行只能處理一個後端，所以對於每個想要的輸出型別，都是獨立分開執行-->
                <executions>
                    <!--html5-->
                    <execution>
                        <id>output-html</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
                        </configuration>
                    </execution>
                    <!--pdf 目前pdf生產會有問題，可採取html用Word文件開啟再另存為的形式-->
             <!--       <execution>
                        <id>output-pdf</id>
                        <phase>test</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
                        </configuration>
                    </execution>-->
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

3. 大致思路

• 1.通過http請求訪問swagger相關介面：/v2/api-docs,將獲取到的json資料儲存至專案的target/asciidoc目錄下，檔名為swagger.json；
• 2.讀取上步中儲存的swagger.json檔案，轉換為html形式的介面文件。

使用

該專案主要類只有一個，包括配置也是在該類中配置，即:
src\test\java\com\beauxie\swagger\export下的SwaggerExportTest.java測試類

• 配置URL
  修改伺服器地址,比如api介面訪問地址為http://127.0.0.1:8080/v2/api-docs,則如下配置:

  /**
     * 伺服器地址
     */
    private static String SERVICE_URL = "http://127.0.0.1:8080";

• 生成文件

修改url地址以後，在專案根目錄下開啟cmd命令視窗，執行以下mvn命令:

mvn test

• 檔案位置
  執行成功以後，會在專案的target/asciidoc/html目錄下，生成一個名為index.html檔案，這個檔案就是swagger離線api文件，用瀏覽器開啟即可檢視。

注意

該專案不需要執行任何程式，只需要修改SwaggerExportTest.java檔案，然後執行相關mvn命令即可。

原始碼地址