博客

背景

对于rest-ful API文档设计，一般都是springfox（底层是swagger）进行代码集成并且自动生成，文档分为在线和离线文档，在线文档一般是html的格式，并且能够进行

mock

，方便测试人员不用写test-case进行测试。

springfox reference 提示已经不支持离线文档的自动生成，推荐使用使用swagger2markup+assicdoctor.以下介绍怎样自动产生离线文档。

swagger2markup

用途：将springfox产生的api-docs api（包括API所有元信息），输出的json格式数据转变为assicdoc文件。

1.依赖包

        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>${swagger2markup.version}</version>
        </dependency>

test 类

    String url="/v2/api-docs";
     try{
     MvcResult mvcResult = mvc.perform(MockMvcRequestBuilders.get(url)).andExpect(status().isOk()).andReturn();
     MockHttpServletResponse response = mvcResult.getResponse();
     String swaggerJson = response.getContentAsString();
     Path outputDirectory = Paths.get("");
      Swagger2MarkupConverter.from(swaggerJson)
        .build()
        .toFolder(outputDirectory);
      }catch(Exception e){
          log.error(e.getMessage());
      } 
}

2.使用插件，通过配置生产

assicdoctor

文件

        <!-- First, use the swagger2markup plugin to generate asciidoc -->
        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>${swagger2markup.version}</version>
            <dependencies>
                <dependency>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-import-files-ext</artifactId>
                    <version>${swagger2markup.version}</version>
                </dependency>
                <dependency>
                    <groupId>io.github.swagger2markup</groupId>
                    <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
                    <version>${swagger2markup.version}</version>
                </dependency>
            </dependencies>
            <configuration>
                <swaggerInput>${swagger.input}</swaggerInput>
                <outputDir>${generated.asciidoc.directory}</outputDir>
                <config>
                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

                    <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
                    <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
                    <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
                    <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>

                    <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
                    <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
                </config>
            </configuration>
            <executions>
                <execution>
                    <phase>test</phase>
                    <goals>
                        <goal>convertSwagger2markup</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

assicdoctor

用途：将assicdoc文件转化为html或者pdf文件。也是依赖包和插件模式（因为时间的原因，只实践了插件模式）

<!-- Run the generated asciidoc through Asciidoctor to generate
             other documentation types, such as PDFs or HTML5 -->
        <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.10.1</version>
                </dependency>
                <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>
                <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>

                <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>

        <!-- specify the main class for the manifest -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>2.4</version>
            <configuration>
                <archive>
                    <manifest>
                        <addClasspath>true</addClasspath>
                        <classpathPrefix>lib/</classpathPrefix>
                        <mainClass>io.github.robwin.swagger2markup.petstore.Application</mainClass>
                    </manifest>
                </archive>
            </configuration>
        </plugin>

        <!-- copy dependencies to the lib directory -->
        <plugin>
            <artifactId>maven-dependency-plugin</artifactId>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>copy-dependencies</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.directory}/lib</outputDirectory>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- copy the generated documents -->
        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <version>2.7</version>
            <executions>
                <execution>
                    <id>copy-resources</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
                        <resources>
                            <resource>
                                <directory>${asciidoctor.html.output.directory}</directory>
                            </resource>
                            <resource>
                                <directory>${asciidoctor.pdf.output.directory}</directory>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>

参考

springfox reference



swagger2markup reference