使用springfox-staticdocs生成swagger离线api文档附带源码

使用springfox-staticdocs生成swagger离线api

因为最近公司部分项目使用swagger来管理在线接口，但在某些场景下需要提供离线的api文档。因此在网上参考了一些博客以后写了一个小项目，只需要配置对应的url，既可生成离线的api文档。该项目的优势在于是一个独立的项目，不要集成到实际开发项目中。

说明

• 只适用于集成swagger框架的项目
• 确保项目的/v2/api-docs接口可访问
• 目前离线文档只支持html5格式，如果需要转化为doc或pdf格式，可以将生成的html5文件选择用world文档打开，然后选择’另存为’其他格式。（建议采用html格式，效果最好）

项目简单说明

1.项目结构

该项目只包含了几个类文件，结构如下图所示:

2.pom文件

如下:

 
<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.0modelVersion>

    <groupId>com.beauxiegroupId>
    <artifactId>swagger.exportartifactId>
    <version>0.0.1-SNAPSHOTversion>
    <packaging>jarpackaging>


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

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

    <dependencies>

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-staticdocsartifactId>
            <version>2.6.1version>
        dependency>
        <dependency>
            <groupId>junitgroupId>
            <artifactId>junitartifactId>
            <version>4.11version>
            <scope>testscope>
        dependency>
    dependencies>

    <build>
        <plugins>
            
            <plugin>
                <groupId>org.apache.maven.pluginsgroupId>
                <artifactId>maven-surefire-pluginartifactId>
                <configuration>
                    <testFailureIgnore>truetestFailureIgnore>
                configuration>
            plugin>
            
            
            <plugin>
                <groupId>org.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.3version>
                
                
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctorgroupId>
                        <artifactId>asciidoctorj-pdfartifactId>
                        <version>1.5.0-alpha.14version>
                    dependency>

                    
                    <dependency>
                        <groupId>org.jrubygroupId>
                        <artifactId>jruby-completeartifactId>
                        <version>1.7.21version>
                    dependency>
                dependencies>

                
                
                <configuration>
                    <sourceDirectory>${asciidoctor.input.directory}sourceDirectory>
                    <sourceDocumentName>index.adocsourceDocumentName>
                    <attributes>
                        <doctype>bookdoctype>
                        <toc>lefttoc>
                        <toclevels>3toclevels>
                        <numbered>numbered>
                        <hardbreaks>hardbreaks>
                        <sectlinks>sectlinks>
                        <sectanchors>sectanchors>
                        <generated>${generated.asciidoc.directory}generated>
                    attributes>
                configuration>
                
                
                <executions>
                    
                    <execution>
                        <id>output-htmlid>
                        <phase>testphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>html5backend>
                            <outputDirectory>${asciidoctor.html.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