使用springfox-staticdocs生成swagger离线api文档附带源码-优快云博客

本文链接：https://blog.youkuaiyun.com/BeauXie/article/details/79835396

使用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命令即可。

源码地址

github
https://github.com/Beauxie/swagger-export
csdn下载
swagger-export