# swagger2doc

**Repository Path**: xfcode-source/swagger2doc

## Basic Information

- **Project Name**: swagger2doc
- **Description**: swagger文档转换工具，将swagger接口转换为word、pdf、markdown、ebook等
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 95
- **Forks**: 41
- **Created**: 2020-12-23
- **Last Updated**: 2025-04-24

## Categories & Tags

**Categories**: doc-tools

**Tags**: None

## README

## 一、介绍
swagger文档转换工具，将swagger定义的接口转换为Word、PDF、markdown、eBook、HTML、DOCBOOK 等

## 二、如何使用

### 1.生成 HTML、PDF、EPUB3、DOCBOOK

#### 说明
支持将swagger.yaml、swagger.json或swagger URL地址,转换为asciidoc,继而转换成其他各种格式,如:HTML、PDF、EPUB3、DOCBOOK等
  主要用到了两个maven插件:
```
   1. swagger2markup-maven-plugin
   2. asciidoctor-maven-plugin
```

#### 操作步骤

 * 1). 配置swagger输入方式
 
  修改pom.xml中定义的<swagger.input>属性。如下：
  
 ```
<!--默认-->
<!--<swagger.input>${asciidoctor.resources}/swagger/swagger.json</swagger.input>-->
<!--<swagger.input>${asciidoctor.resources}/swagger/swagger.yaml</swagger.input>-->
<swagger.input>http://127.0.0.1:8089/v2/api-docs</swagger.input>
```

 * 2). 配置文档转换后的输出路径

```
  <!--默认-->
    <generated.asciidoc.directory>${project.build.directory}/asciidoc/asciidoc</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>
    <asciidoctor.epub3.output.directory>${project.build.directory}/asciidoc/epub3</asciidoctor.epub3.output.directory>
    <asciidoctor.docbook.output.directory>${project.build.directory}/asciidoc/docbook</asciidoctor.docbook.output.directory>
```    

* 3). 生成文档
 
 执行maven命令
 
 ```
 mvn test  
```

生成目录如下：
```
├─asciidoc
├─docbook
├─epub3
├─html
└─pdf
```

####  注意事项
1. 若你设计的API中没有用TAG分类,则必须将pom中的<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy> 改为AS-IS或者直接注释掉
2. pdf主题配置过于耗时,这里只是简单设置了下,如果对样式不满意,可以自行参考官方文档配置pdf的样式
3. 若要修改pdf文件字体可将fonts下的字体文件换成你的字体,并在custom-theme.yml中修改font -> catalog的配置,具体请参考[pdf文件样式设置指引](https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc)                                                  
4. 因为用到的两个插件不会自动执行,所以指定了插件执行所在的阶段为test,故maven插件目标包含test环节的命令都可以执行。执行完毕后,将在target/asciidoc下会看到生成的文档。

### 2、生成word

支持swagger2,swagger3,openapi3.0 生成Word，启动项目后，通过调用接口的方式生成文档。

#### 操作步骤  

 1) . 执行执行DocApplication.java，启动工程，访问地址： http://127.0.0.1:8089/swagger-ui.html
 2) . 选择文档生成方式，swagger2Word支持如下三种方式方式生成 word 文档： 
  * swagger json 的资源地址： 例如：http://127.0.0.1:8089/v2/api-docs 
  * 可以通过上传 json 文件
  * 可以直接输入 json 字符串
  
  接口如下：
  
 ![image](resources/word/swagger_doc_api.png)    
  
 3) . 生成的 WORD 示例：  
 
![image](resources/word/swagger_doc_example.png)

####  注意事项   

模版定制及样式修改详见: resource/templates/word.html
  


## 三、参考链接:
> * [swagger2markupmaven插件官方文档](http://swagger2markup.github.io/swagger2markup/1.0.1/)
> * [asciidoctor maven插件官方文档](http://asciidoctor.org/docs/asciidoctor-maven-plugin/)
> * [pom中配置的asciidoctor属性说明](http://asciidoctor.org/docs/asciidoctor-maven-plugin/#configuration-options)
> * [asciidoctor maven插件中文说明](https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/README_zh-CN.adoc)
> * [asciidoctor maven插件使用范例](https://github.com/asciidoctor/asciidoctor-maven-examples)
> * [pdf文件样式设置指引](https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc)
> * [pdf文件自定义字体设置参考](https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#custom-fonts)
> * [swagger-gendoc](https://github.com/woshihoujinxin/swagger-gendoc.git)
> * [restdocs](https://github.com/quiterr/restdocs.git)
> * [swagger2word](https://github.com/JMCuixy/swagger2word/)
  
## 四、其他
如果觉得不错,请加个星,不甚感激!!!