Swggaer2Markup生成离线文档

Swagger2

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
Swagger 是一种通用的，和编程语言无关的 API 描述规范。

Swagger2Markup

wagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

开发步骤

1. 引入常见依赖

 <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.6.0</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.6.0</version>
    </dependency>

    <dependency>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup</artifactId>
      <version>1.3.1</version>
    </dependency>


    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</version>
      <scope>test</scope>
    </dependency>

    <!--    替换swagger2markup内部的jar-->
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-core</artifactId>
      <version>1.5.16</version>
    </dependency>
    <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-models</artifactId>
      <version>1.5.16</version>
    </dependency>

2. POM引入插件

     <plugin>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoctor-maven-plugin</artifactId>
           <version>1.5.6</version>
   
           <dependencies>
   
             <dependency>
               <groupId>org.asciidoctor</groupId>
               <artifactId>asciidoctorj-pdf</artifactId>
               <version>1.5.0-alpha.10.1</version>
             </dependency>
    
   
           </dependencies>
   
           <configuration>
             <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
             <outputDirectory>./docs/asciidoc/pdf</outputDirectory>
             <headerFooter>true</headerFooter>
             <doctype>book</doctype>
             <backend>pdf</backend>
             <sourceHighlighter>coderay</sourceHighlighter>
             <attributes>
               <!--菜单栏在左边-->
               <toc>left</toc>
               <!--多标题排列-->
               <toclevels>3</toclevels>
               <!--自动打数字序号-->
               <sectnums>true</sectnums>
             </attributes>
           </configuration>
         </plugin>
   

3. 配置swagger

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
     @Bean
     public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(apiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.example"))
           .paths(PathSelectors.any())
           .build();
     }
   
     //构建 api文档的详细信息函数
     private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
           //页面标题
           .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
           //创建人
           .contact(new Contact("zorpz", "https://blog.csdn.net", ""))
           //版本号
           .version("1.0")
           //描述
           .description("API 描述")
           .build();
     }
   }
   

4. API 示例

   @RequestMapping("test")
   @RestController
   @Api(tags = "测试")
   public class TestController {
   
     @GetMapping("hi")
     @ApiOperation(value = "根据name查询设备信息", notes = "查询数据库中某个设备的信息")
     public String hi(@ApiParam(name = "name", value = "设备名称", required = true)String name) {
       return "hahha";
     }
   }
   

5. 启动服务，输入http://localhost:8080/v2/api-docs 可查看JSON 格式的API

6. 编写测试类，运行生成adoc文件

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class Demo1ApplicationTests {

  @Test
  public void generateAsciiDocsToFile() throws Exception {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.ZH)
        .withPathsGroupedBy(GroupBy.TAGS)
        .withGeneratedExamples()
        .withoutInlineSchema()
        .build();

    Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
        .withConfig(config)
        .build()
        .toFile(Paths.get("./docs/asciidoc/generated/all"));
  }

}

7. 运行asciidoc插件： asciidoc:process-asciidoc生成PDF文件。

常见问题

1. 出现java.lang.NoSuchFieldError: MULTIPLE_OF

   解决方法： 引入依赖的houlianggejar进行替换。

2. 导出的PDF 文字缺失

   原因： 官方的字体对中文的兼容不好。

   解决方法：

   1. clone一位博主的项目 https://github.com/nitianziluli/swagger2pdf ，进行解压；

   2. 打开maven仓库对应路径的jar： org/asciidoctor/asciidoctorj-pdf/1.5.0-alpha.10.1，解压缩打开；

   3. 进入gems/asciidoctor-pdf-1.5.0.alpha/data 目录；

   4. 进入clone项目的font目录，拷贝KaiGenGothicCN开头的字体到压缩打开的font路径；

      [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Ayx8BV7S-1586408939448)(clone字体.png)]

      [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-XwnLndTb-1586408939456)(拷贝字体.png)]

   5. 修改data/themes目录下的default-theme.yml，修改对应的字体

      [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lhtjZPdK-1586408939468)(theme.png)]

   6. 重新运行asciidoc插件，pdf完美生成。