Spring boot 2.1.9+Swagger2.9.2+swagger2markup生成离线HTML和pdf接口文档

1. 首先引入maven依赖
    a：首先是properties的版本依赖
           

   <properties>
           <java.version>1.8</java.version>
           <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
           <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
           <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
           <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
           <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</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>
           <swagger.input>${project.basedir}/src/docs/swagger/swagger.json</swagger.input>
           <swagger2markup.version>1.2.0</swagger2markup.version>
           <spring-restdocs-mockmvc.version>2.0.2.RELEASE</spring-restdocs-mockmvc.version>
           <springfox-staticdocs.version>2.6.1</springfox-staticdocs.version>
       </properties>

   
    b：引入repositories加载
         

   <repositories>
           <repository>
               <id>jcentral</id>
               <name>bintray</name>
               <url>http://jcenter.bintray.com</url>
               <snapshots>
                   <enabled>false</enabled>
               </snapshots>
           </repository>
           <repository>
               <id>jcenter-snapshots</id>
               <name>jcenter</name>
               <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
           </repository>
       </repositories>

   
    c：引入jar的相关依赖
       

   <!--offline doc-->
   <dependency>
   	<groupId>org.springframework.restdocs</groupId>
   	<artifactId>spring-restdocs-mockmvc</artifactId>
   	<version>${spring-restdocs-mockmvc.version}</version>
   	<scope>test</scope>
   </dependency>
   <dependency>
   	<groupId>io.github.swagger2markup</groupId>
   	<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
   	<version>${swagger2markup.version}</version>
   	<scope>test</scope>
   </dependency>
   <dependency>
   	<groupId>io.springfox</groupId>
   	<artifactId>springfox-staticdocs</artifactId>
   	<version>${springfox-staticdocs.version}</version>
   </dependency>
   <!-- swagger集成 -->
   <dependency>
   	<groupId>io.springfox</groupId>
   	<artifactId>springfox-swagger2</artifactId>
   	<version>2.9.2</version>
   </dependency>
   <!-- 默认swagger-ui -->
   <dependency>
   	<groupId>io.springfox</groupId>
   	<artifactId>springfox-swagger-ui</artifactId>
   	<version>2.9.2</version>
   </dependency>

   
    d：引入打包等相关插件
          

   <plugins>
               <!--打包为可执行jar  -->
               <plugin>
                   <groupId>org.springframework.boot</groupId>
                   <artifactId> spring-boot-maven-plugin</artifactId>
                   <configuration>
                       <fork>true</fork>
                   </configuration>
               </plugin>
               <!--自定义配置spring Boot使用的JDK版本-->
               <plugin>
                   <artifactId>maven-compiler-plugin</artifactId>
                   <configuration>
                       <source>1.8</source>
                       <target>1.8</target>
                   </configuration>
               </plugin>
               <!--下面定义Swagger2离线文档的生成插件-->
               <!-- 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.outputLanguage>ZH</swagger2markup.outputLanguage>
                           <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>
   
               <!-- 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.6</version>
                   <!-- Include Asciidoctor PDF for pdf generation -->
                   <dependencies>
                       <dependency>
                           <groupId>org.asciidoctor</groupId>
                           <artifactId>asciidoctorj-pdf</artifactId>
                           <version>1.5.0-alpha.16</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>
           </plugins>

2. 在配置文件中配置swagger的开关，因为有的环境不需要这个接口文档(比如生产环境)，直接在.properties或者yaml配置文件中配置即可
    
3. 在项目的src目录下创建docs目录，文件如下：
    
    其中index.adoc文件内容如下：
    

   include::{generated}/overview.adoc[]
   include::{generated}/paths.adoc[]
   include::{generated}/security.adoc[]
   include::{generated}/definitions.adoc[]

   swagger.json的内容是项目启动后访问如下路径获取的内容（属于Swagger2生成的接口Api数据，开发完成之后需要到这个路径下
   获取最新的数据，拷贝到这个文件里面）
   ip:port/swagger-ui.html

4. 下面创建SwaggerConfig.java配置
    

   package com.kgf.mall.utils;
   
   import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   @ConditionalOnExpression("${swagger.enable:true}")
   public class SwaggerConfig {
       /***
        * 用来配置swagger,指定扫描的区域
        * @return
        */
       @Bean
       public Docket createRestApi(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.kgf.mall"))//指定需要扫描的路径
                   .paths(PathSelectors.any())
                   .build();
       }
   
       /***
        * 创建文档的基本信息
        * @return
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   //标题
                   .title("Shopping-mall-web API")
                   .description("Shopping-mall-web接口文档")
                   .termsOfServiceUrl("http://localhost:8888/login")
                   //设置联系方式
                   .contact(new Contact("KGF","https://blog.csdn.net/K_520_W","xxx@163.com"))
                   .version("1.0")
                   .build();
       }
   }
   

    

5. 下面我们可以使用Swagger2对接口以及实体类进行注解，例如下：
    a:实体注解
          

   package com.kgf.mallCommon.model;
   
   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   import lombok.Data;
   
   import java.io.Serializable;
   
   @Data
   @ApiModel(value = "SysUser",description = "用户信息实体类")
   public class SysUser implements Serializable {
   
       private static final long serialVersionUID = 1196391676154975930L;
       /**主键ID**/
       @ApiModelProperty(value = "主键ID",name = "id")
       private String id;
       /**登录账号**/
       @ApiModelProperty(value = "登录账号",name = "userName")
       private String userName;
       /**昵称**/
       @ApiModelProperty(value = "昵称",name = "name_1")
       private String name_1;
       /**手机号码**/
       @ApiModelProperty(value = "手机号码",name = "phone")
       private String phone;
       /**性别**/
       @ApiModelProperty(value = "性别",name = "sex")
       private String sex;
       /**年龄**/
       @ApiModelProperty(value = "年龄",name = "age")
       private Integer age;
       /**生日**/
       @ApiModelProperty(value = "生日",name = "birthday")
       private String birthday;
       /**邮箱**/
       @ApiModelProperty(value = "邮箱",name = "email")
       private String email;
       /**公司**/
       @ApiModelProperty(value = "公司",name = "company")
       private String company;
       /**照片地址**/
       @ApiModelProperty(value = "照片地址",name = "profilePicture")
       private String profilePicture;
       /**密码**/
       @ApiModelProperty(value = "密码",name = "userPass")
       private String userPass;
       /**是否锁定：0-正常,1-锁定**/
       @ApiModelProperty(value = "是否锁定：0-正常,1-锁定",name = "isLocked")
       private String isLocked;
       /**用户状态：0-正常,1-删除**/
       @ApiModelProperty(value = "用户状态：0-正常,1-删除",name = "status")
       private String status;
       private String createdBy;
       private String createdDate;
       private String updatedBy;
       private String updatedDate;
   
   }
   

   
    b：Controller层注解
         

   package com.kgf.mall.controller.login;
   
   import com.kgf.mall.model.UIResult;
   import com.kgf.mall.service.impl.LoginServiceImpl;
   import com.kgf.mallCommon.model.SysUser;
   import io.swagger.annotations.Api;
   import io.swagger.annotations.ApiImplicitParam;
   import io.swagger.annotations.ApiImplicitParams;
   import io.swagger.annotations.ApiOperation;
   import org.springframework.beans.factory.annotation.Autowired;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RequestMethod;
   import org.springframework.web.bind.annotation.RestController;
   
   import java.util.Map;
   
   @RestController
   @RequestMapping("login")
   @Api(tags = "用户登录/退出模块")
   public class LoginController {
   
       @Autowired
       private LoginServiceImpl loginService;
   
       /**
        * 用户登录方法
        * @param sysUser
        * @return
        */
        @ApiOperation(value = "用户登录接口",notes ="通过用户名密码登录系统" )
        @ApiImplicitParams({
                @ApiImplicitParam(name = "userName", value = "用户账号", required = true, dataType = "String"),
                @ApiImplicitParam(name = "userPass", value = "用户密码", required = true, dataType = "String")
        })
        @RequestMapping(value="/userLogin",method = {RequestMethod.POST})
        public UIResult userLogin(SysUser sysUser){
          UIResult uiResult = new UIResult(null,true,null);
          try {
              Map<String,Object> result =  loginService.userLogin(sysUser);
              if (!result.get("code").toString().equals("200")){
                  uiResult.setFlag(false);
                  uiResult.setMsg(result.get("msg").toString());
              }else{
                  uiResult.setResult(result);
              }
          }catch (Exception e){
              e.printStackTrace();
              uiResult.setFlag(false);
              uiResult.setMsg(e.getMessage());
          }
           return uiResult;
         }
   
       /***
        * 用户退出方法
        * @return
        */
       @ApiOperation(value = "用户退出接口",notes = "退出当前用户")
       @RequestMapping(value="/userLogout",method = RequestMethod.POST)
       public UIResult userLogout(){
           UIResult uiResult = new UIResult(null,true,null);
           try {
               uiResult.setResult(loginService.userLogout());
           }catch (Exception e){
               e.printStackTrace();
               uiResult.setFlag(false);
               uiResult.setMsg(e.getMessage());
           }
           return uiResult;
       }
   
       /***
        * 获取当前登录的用户信息
        * @return
        */
       @ApiOperation(value = "查询当前登录用户信息",notes = "查询当前登录用户信息")
       @RequestMapping(value = "/queryLoginUser",method = RequestMethod.POST)
       public SysUser queryLoginUser(){
           SysUser sysUser = null;
           try {
                sysUser = loginService.queryLoginUser();
           }catch (Exception e){
               e.printStackTrace();
           }
           return sysUser;
       }
   }
   

    

6. 最后解决生成的PDF中文缺失以及空白的问题(主要就是中文字体问题)
    a：在我们的maven仓库中找到我们引入的asciidoctorj-pdf-1.5.0-alpha.16.jar
    b：下载网上找到的字体
           
          下面链接可获取字体：
          链接：https://pan.baidu.com/s/1hl5BbObuQ5I2SYAW5EZnKA 
          提取码：k0c2
    c：进入该jar的asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts目录下
          将上面准备的字体加入到里面
          
    d：修改该jar的asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes目录下的default-theme.yml文件
          
7. 最后编译打包项目可看到生成离线的文件
    a:pdf
        
   b：html
        
   c：启动项目，访问在线Api