基于swagger2生成在线RESTful API HTML文档以及生成离线PDF文档 乱码 文字丢失 解决办法

项目基础

springboot 2.02
springfox-swagger2/springfox-swagger-ui 2.8
io.github.swagger2markup 1.3.3

在需要加入的项目RESTful API HTML文档引入依赖

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.8.0version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.8.0version>
        dependency>

在springboot 启动 Application同级创建一个swagger2配置文件

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的需要生成文档的包位置"))
                .paths(PathSelectors.any())
                .build();
    }


}

加入文档注解

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class AreaDto implements Serializable {
    @ApiParam(value = "区域名", required = true)
    private String name;
}

@RestController
@RequestMapping(value="/pc/area")
public class AreaController {

    @GetMapping(value="/")
    @ApiOperation("获取区域列表")
    public Result getAreaList() {
        return Result.builder().build();
    }

    @PostMapping(value="/")
    @ApiOperation("新增一个区域")
    @ApiImplicitParam(name = "area", value = "区域实体DTO", required = true, dataType = "AreaDto")
    public Result postUser(@ModelAttribute AreaDto area) {
        return  Result.builder().success(true).build();
    }

    @PutMapping(value="/{id}")
    @ApiOperation("根据ID更新一个区域的信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "区域ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "area", value = "区域DTO", required = true, dataType = "AreaDto")
    })
    public Result putUser(@PathVariable Long id, @ModelAttribute AreaDto area) {
        return  Result.builder().success(false).errorCode(ErrorCode.USER_NOT_FOUND).build();
    }

    @DeleteMapping(value="/{id}")
    @ApiOperation("根据ID删除一个区域")
    @ApiImplicitParam(name = "id", value = "区域id", required = true, dataType = "Long")
    public Result deleteUser(@PathVariable Long id) {
        return  Result.builder().success(true).successCode(SuccessCode.FORWARDING).build();
    }
}

启动项目，浏览http://localhost:8080/swagger-ui.html即可看到日志

如果需要进行下一步，在这一步需要保存http://localhost:8080/v2/api-docs返回的json数据

接下来是生成离线PDF、HTML、ADOC的步骤，不需要可以跳过

下载https://github.com/Swagger2Markup/spring-swagger2markup-demo下的项目

打开项目，修改POM文件

把swagger.input修改成年上面保存的json数据

进行编译

mvn test或者用idea的工具进行编译，打开编译后的目录，可以发现我们需要的文件已经
生成

查看PDF，如果发现乱码，请继续往下看

https://github.com/asciidocfx/AsciidocFX/releases
在releases中下载你需要的版本

安装完成后，通过该软件打开ADOC，然后点击右上角转存为PDF，可以发现已经没有乱码，如果需要转换DOC，可以借助其他工具（如Adobe Acrobat Reader）

总结

在转换成ＰＤＦ过程出现乱码、文件丢失等现象，可能是配置中出了问题，对于我来说文档只需要生成一次，因此选择了最节省时间的一种方案，有兴趣的朋友可以看下https://github.com/Swagger2Markup/swagger2markup。