Swagger2构建离线RESTful API

Swagger2 生成 离线 PDF、HTML文档

用途：Swagger是一个简单但功能强大的API表达工具，使用Swagger生成API，我们可以得到交互式文档

集成：引入依赖，配置Swagger，设置静态资源映射

使用：@ApiOperation，@ApiImplicitParams，@ApiImplicitParam注解

若本篇文章有看不懂的地方可见上篇文章有详细讲解

配置pom.xml生成离线文档

<properties>
    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
    <generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
    <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.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>

<!--springfox-staticdocs 生成静态文档-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-staticdocs</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
</dependency>

<build>
    <finalName>gunsSwagger2</finalName>
      <plugins>
          <!-- 生成离线文件 -->
          <!--通过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>
              <!-- Run the generated asciidoc through Asciidoctor to generate
                      other documentation types, such as PDFs or HTML5 -->
              <!-- 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-->
                  <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>

生成离线文件

建立一个测试类（这里也可以使用Controller调用service生成adoc文件，较麻烦）

@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest(classes = SwaggerStaticDocTest.class)
@ComponentScan("com.agesun.witness")
public class SwaggerStaticDocTest {
    private String snippetDir = "target/generated-snippets";
    private String outputDir  = "target/asciidoc";
    @Autowired
    private MockMvc mockMvc;
    @After
    public void Test() throws Exception {
        // 得到swagger.json,写入outputDir目录中
        mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
                .andExpect(status().isOk())
                .andReturn();
        // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
        // 这个outputDir必须和插件里面<generated></generated>标签配置一致
        Swagger2MarkupConverter.from(outputDir + "/swagger.json")
                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
                .withExamples(snippetDir)
                .build()
                .intoFolder(outputDir);// 输出
    }
    @Test
    public void TestApi() throws Exception {
        /*mockMvc.perform(get("/user/getUser").param("name", "FLY")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(MockMvcRestDocumentation.document("getUser", preprocessResponse(prettyPrint())));*/
    }
}

terminal 执行 mvn test 会先执行test文件在执行生成文件命令，便可获取离线文件

文件目录 target-->asciidoc 中