# swagger2pdf

**Repository Path**: hsdeamy/swagger2pdf

## Basic Information

- **Project Name**: swagger2pdf
- **Description**: 使用springBoot+springFox+swagger2markup+asciidoctorj-pdf，生成HTML和PDF格式的接口文档，也解决了PDF文档中文显示为空白的问题
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2021-08-10
- **Last Updated**: 2021-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 说明
本项目 fork 自 https://gitee.com/nitianziluli/swagger2pdf。

在源项目基础上增加了从本地 swagger.json 生成html/pdf文档的功能。

了解更多信息，请参考[源项目](https://gitee.com/nitianziluli/swagger2pdf)。

# 前提
因项目使用 maven 管理，因此需要先了解 maven ，会将 maven 配置到 path 中。
不会将 maven 配置到 path 中，也不影响使用，但此处不介绍，可自行百度。

# 使用步骤

1. 修改`swagger.json`。

`swagger.json` 位置在 `swagger2pdf/src/test/resources` 目录下。将该文件内容替换为你自己的。

2. 启动命令

在 `swagger2pdf` 目录下执行命令：

```
mvn clean test
```

3. 找到 html/pdf 格式的接口文档

```
swagger2pdf/target/asciidoc
```

# 实现原理：

1. 先利用`SpringFox`库生成`RESTful API`（`swagger.json`）。本项目跳过了此步。如需要此步，参考源项目。
2. 再利用`Swagger2Markup` Maven插件生成`asciidoc`文档。
3. 最后利用`asciidoctor` Maven插件生成 html 或 pdf 文件。

# 其他说明
共有3个方式生成 html 或 pdf 文件：
1. 在接口项目中生成 html 或 pdf 文件。
2. 另起一个项目生成 html 或 pdf 文件。生成过程中通过访问网络地址`/v2/api-docs`获取`swagger.json`。
3. 另起一个项目生成 html 或 pdf 文件。生成前将`swagger.json`放到`src/test/resources` 目录下。

前2个方式是源项目提供的，本项目提供第3个方式。
建议使用第2个或第3个方式。