# showdoc-api-plugin

**Repository Path**: chansirs/showdoc-api-plugin

## Basic Information

- **Project Name**: showdoc-api-plugin
- **Description**: No description available
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-08-23
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# swagger-docgen

`swagger-docgen` 是一个独立的 Swagger/OpenAPI 接口文档生成工具。

当前版本支持从 Swagger/OpenAPI JSON 或 YAML 文件生成 Markdown、HTML、Word 和 PDF 文档。HTML 与 PDF 共用一套出版物风格，PDF 由本地 Chrome/Chromium 打印生成。

## 支持范围

- Swagger 2.0
- OpenAPI 3.0
- JSON 输入
- YAML/YML 输入
- 本地文件输入
- HTTP/HTTPS 地址输入
- Markdown 输出
- HTML 输出
- Word DOCX 输出
- PDF 输出

文档会结构化展示以下信息：

- Info、联系方式、服务条款、License 和外部文档
- Swagger 2.0 的 host/basePath/schemes/consumes/produces
- OpenAPI 3.0 的 servers 和 server variables
- Paths、Operations、Path 级公共参数、Operation ID、Tags 和废弃标记
- Query/Path/Header/Cookie/Form/Body 参数及序列化方式
- Request Body、Responses、Headers、Examples 和所有响应 MIME 类型
- API Key、HTTP Basic/Bearer、OAuth2、OpenID Connect 及安全要求
- Schema 属性、必填项、枚举、数值/长度/数组约束和组合 Schema
- Callbacks、Links、可复用组件、数据模型和 `x-*` 扩展

为减少信息丢失，复杂 Schema、Callbacks、Links、可复用组件和扩展字段会同时保留原始 JSON 表示。

当前限制：

- 支持 Swagger 2.0 和 OpenAPI 3.0.x；OpenAPI 3.1 会明确拒绝，避免按错误语义生成文档。
- 支持当前文档内的本地 `$ref`。外部文件或 URL `$ref` 会列入“外部引用”章节，但不会自动下载和内联。
- `oneOf`、`anyOf`、`allOf` 等高级 Schema 会提供字段展开、组合规则标记和原始 Schema；不会模拟完整的 JSON Schema 校验行为。

## 使用方式

```shell
go run . -input ./swagger.yml -output ./api.md -format markdown
```

也可以从 URL 读取：

```shell
go run . -input https://petstore.swagger.io/v2/swagger.json -output ./api.md
```

生成 Word：

```shell
go run . -input ./swagger.yml -output ./api.docx -format docx
```

生成 HTML：

```shell
go run . -input ./swagger.yml -output ./api.html -format html
```

生成 PDF：

```shell
go run . -input ./swagger.yml -output ./api.pdf -format pdf
```

生成英文文档（规范自身的摘要、描述等业务内容保持原文）：

```shell
go run . -input ./swagger.yml -output ./api-en.pdf -format pdf -lang en-US
```

输出到 stdout：

```shell
go run . -input ./swagger.json -output -
```

兼容旧参数名：

```shell
go run . -swagger ./swagger.json -output ./api.md
```

## 参数说明

| 参数 | 必填 | 默认值 | 说明 |
|:--|:--|:--|:--|
| `-input` | 是 | - | Swagger/OpenAPI JSON 或 YAML 的本地路径、绝对路径或 http(s) 地址 |
| `-swagger` | 否 | - | 兼容旧版本，等同于 `-input` |
| `-output` | 否 | 按格式决定 | 输出文件路径；默认 `api.md`/`api.html`/`api.docx`/`api.pdf`；Markdown/HTML 可使用 `-` 输出到 stdout |
| `-format` | 否 | `markdown` | 输出格式；支持 `markdown`/`md`/`html`/`htm`/`docx`/`pdf` |
| `-lang` | 否 | `zh-CN` | 文档结构语言；支持 `zh-CN`/`en-US`，不会自动翻译规范自身的摘要和描述 |

## HTML/Word/PDF 依赖

`html` 和 `docx` 导出依赖系统已安装 `pandoc`。

Word 导出使用独立的 DOCX 样式模板，包含 A4 页面、封面、二级目录、页眉页脚和页码、分级标题、可换行表格、表头底色以及 JSON 代码块样式。模板会在导出时根据 Pandoc 默认 reference.docx 自动生成，不会覆盖用户已有的 Word 模板。首次在 Microsoft Word 中打开文档时，目录字段会自动更新；LibreOffice 的无界面转换不会执行字段刷新，打开后刷新目录即可显示页码。

`pdf` 导出依赖系统已安装：

- `pandoc`
- Google Chrome 或 Chromium

PDF 导出先生成同名 HTML，再使用本地 Chrome/Chromium 的打印能力生成 PDF。例如输出 `api.pdf` 时，会同时保留 `api.html`。程序不会下载浏览器；可以通过 `SWAGGER_DOCGEN_CHROME` 显式指定本地浏览器可执行文件。

HTML/PDF 样式与 Word 的设计语言保持一致，包含封面、一级/二级目录、A4 打印页面、分级标题、接口独立分页、可换行表格、重复表头、浅色代码块和附录区域。PDF 同时写入标准文档大纲，可在 Chrome、Adobe Acrobat、福昕等阅读器的书签侧边栏中导航；HTML 可直接作为静态文档发布或二次编辑。

如果没有安装 Pandoc，可以先只导出 Markdown：

```shell
go run . -input ./swagger.yml -output ./api.md -format markdown
```

安装 Pandoc 后可导出 Word：

```shell
go run . -input ./swagger.yml -format docx
```

安装 Pandoc 和 Chrome/Chromium 后可离线导出 PDF：

```shell
go run . -input ./swagger.yml -format pdf
```

也可以显式指定本地 Chrome：

```shell
SWAGGER_DOCGEN_CHROME=/opt/google/chrome go run . -input ./swagger.yml -format pdf
```

## 构建

```shell
go build -o swagger-docgen .
```

构建后使用：

```shell
./swagger-docgen -input ./swagger.yml -output ./api.md
```

## 导出链路

当前导出链路：

```text
Swagger/OpenAPI JSON/YAML -> Markdown -> HTML -> PDF
                                      -> DOCX
```

HTML 与 PDF 共用同一个模板和 CSS，样式调整会同时作用于网页文档和 PDF；DOCX 保持独立的 Word 样式模板。