Swagger UI 导出文档从入门到实战指南_Java

1. 引言

swagger ui 是 openapi 规范（原 swagger 规范）最流行的可视化工具之一，它能够将接口定义文件渲染成交互式的 api 文档页面。在实际开发中，我们经常需要将 swagger ui 中的接口文档导出为离线文档、pdf 或 markdown 文件，用于团队协作、客户交付或知识沉淀。本文将围绕 swagger ui 导出文档这一主题，介绍多种导出方案，并提供丰富的代码实例，帮助你在不同场景下快速完成文档导出。

2. 准备工作

在开始导出之前，需要确保本地环境满足以下条件：

已安装 java 8 或更高版本（用于运行 swagger 相关工具）。
已安装 node.js 12 及以上版本（用于运行 npm 生态的导出工具）。
已有一个可访问的 swagger ui 页面或 openapi 描述文件（如 swagger.json、openapi.yaml）。

下面是一个典型的 spring boot 项目集成 swagger 的配置示例，用于生成 openapi 描述文件。

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.spi.documentationtype;
import springfox.documentation.spring.web.plugins.docket;
@configuration
public class swaggerconfig {
@bean
public docket createrestapi() {
    return new docket(documentationtype.oas_30)
            .apiinfo(apiinfo())
            .select()
            .apis(requesthandlerselectors.basepackage("com.example.controller"))
            .paths(pathselectors.any())
            .build();
}
private apiinfo apiinfo() {
return new apiinfobuilder()
.title("示例 api 文档")
.description("用于演示 swagger ui 导出文档的示例项目")
.version("1.0.0")
.build();
}
}

启动项目后，访问 http://localhost:8080/swagger-ui/index.html 即可看到 swagger ui 页面，同时后端会暴露 /v3/api-docs 接口返回 openapi json 数据。

3. 导出 openapi 原始 json

导出文档的第一步通常是获取 openapi 原始描述文件。swagger ui 页面本身提供了下载入口，也可以通过命令行工具直接拉取。

3.1 通过 swagger ui 页面下载

在 swagger ui 页面右上角，点击「explore」旁边的下拉菜单，选择「download openapi specification」即可下载 json 文件。这种方式适合人工操作，但无法自动化。

3.2 通过 curl 命令拉取

在 ci/cd 流水线中，更推荐使用 curl 直接拉取 openapi 描述文件：

curl -o swagger.json http://localhost:8080/v3/api-docs

如果接口需要认证，可以携带 token：

curl -h "authorization: bearer your_token" \
     -o swagger.json \
     http://localhost:8080/v3/api-docs

拉取成功后，可以用 jq 工具快速校验 json 格式是否合法：

jq . swagger.json > /dev/null && echo "json 格式合法"

4. 使用 swagger2markup 导出 markdown 和 asciidoc

swagger2markup 是一个 java 库，可以将 openapi 描述文件转换为 markdown、asciidoc 或 confluence 格式。它非常适合在 maven 或 gradle 构建流程中集成。

4.1 maven 依赖配置

<dependency>
    <groupid>io.github.swagger2markup</groupid>
    <artifactid>swagger2markup</artifactid>
    <version>1.3.3</version>
</dependency>

4.2 编写 java 转换代码

import io.github.swagger2markup.groupby;
import io.github.swagger2markup.language;
import io.github.swagger2markup.swagger2markupconfig;
import io.github.swagger2markup.swagger2markupconverter;
import io.github.swagger2markup.builder.swagger2markupconfigbuilder;
import io.github.swagger2markup.markup.builder.markuplanguage;
import java.nio.file.path;
import java.nio.file.paths;
public class swaggertomarkdown {
public static void main(string[] args) throws exception {
    path inputfile = paths.get("swagger.json");
    path outputdir = paths.get("docs");
swagger2markupconfig config = new swagger2markupconfigbuilder()
        .withmarkuplanguage(markuplanguage.markdown)
        .withoutputlanguage(language.zh)
        .withpathsgroupedby(groupby.tags)
        .withgeneratedexamples()
        .build();
swagger2markupconverter converter = swagger2markupconverter
.from(inputfile)
.withconfig(config)
.build();
converter.tofolder(outputdir);
system.out.println("markdown 文档已生成到: " + outputdir.toabsolutepath());
}
}

运行上述代码后，会在 docs 目录下生成多个 markdown 文件，包括 overview.md、paths.md、definitions.md 等。

4.3 转换为 asciidoc

只需将 markuplanguage.markdown 替换为 markuplanguage.asciidoc，即可输出 asciidoc 格式：

swagger2markupconfig config = new swagger2markupconfigbuilder()
        .withmarkuplanguage(markuplanguage.asciidoc)
        .withoutputlanguage(language.zh)
        .build();

5. 使用 widdershins 导出 markdown

widdershins 是 node.js 生态中非常流行的 openapi 转 markdown 工具，它生成的文档结构清晰，支持 openapi 3.0 和 swagger 2.0。

5.1 安装 widdershins

npm install -g widdershins

5.2 基本用法

widdershins --language zh \
            --summary \
            --omitheader \
            --search false \
            swagger.json \
            -o api-docs.md

参数说明：

--language zh：指定输出语言为中文。
--summary：只输出接口摘要，减少正文内容。
--omitheader：省略文档头部信息。
--search false：关闭搜索功能。

5.3 在 node.js 项目中以编程方式调用

const widdershins = require('widdershins');
const options = {
language: 'zh',
summary: true,
omitheader: true,
search: false
};
widdershins.convert('swagger.json', options)
.then(markdown => {
const fs = require('fs');
fs.writefilesync('api-docs.md', markdown);
console.log('markdown 文档生成成功');
})
.catch(err => {
console.error('转换失败:', err);
process.exit(1);
});

6. 使用 redoc-cli 导出 html 和 pdf

redoc-cli 是 redoc 官方提供的命令行工具，可以将 openapi 描述文件打包成独立的 html 文件，也可以借助 headless 浏览器导出 pdf。

6.1 安装 redoc-cli

npm install -g redoc-cli

6.2 导出独立 html 文件

redoc-cli bundle swagger.json \
    --options.theme.colors.primary.main=#1890ff \
    --title "示例 api 文档" \
    -o api-docs.html

生成的 html 文件是自包含的，包含所有 css 和 javascript，可以直接通过浏览器打开，也可以部署到静态服务器。

6.3 导出 pdf 文件

redoc-cli bundle swagger.json \
    --output api-docs.html \
    --options.theme.colors.primary.main=#1890ff
npx --yes puppeteer print-to-pdf api-docs.html api-docs.pdf

这里使用 puppeteer 的 print-to-pdf 命令将 html 渲染为 pdf。如果 pdf 内容被截断，可以调整页面尺寸：

npx --yes puppeteer print-to-pdf \
    --landscape \
    --format a4 \
    api-docs.html api-docs.pdf

7. 使用 swagger ui 自带打印功能导出 pdf

swagger ui 页面本身支持浏览器打印，通过调整打印样式可以导出较为整洁的 pdf 文件。具体步骤如下：

在浏览器中打开 swagger ui 页面。
按 ctrl + p（windows）或 command + p（mac）打开打印对话框。
在「目标打印机」中选择「另存为 pdf」。
在「更多设置」中，将「纸张大小」设为 a4，「边距」设为「无」。
勾选「背景图形」选项，确保接口标签和颜色正常显示。
点击「保存」即可导出 pdf 文件。

这种方式的优点是无需额外安装工具，缺点是页面中的折叠面板默认只展示展开状态，需要手动展开所有接口后再打印。

8. 使用 openapi generator 导出多种格式

openapi generator 是一个功能强大的代码生成工具，除了生成客户端 sdk 和服务端骨架代码外，也可以生成 html 和 markdown 格式的文档。

8.1 安装 openapi generator cli

npm install -g @openapitools/openapi-generator-cli

8.2 生成 html 文档

openapi-generator-cli generate \
    -i swagger.json \
    -g html \
    -o docs/html

8.3 生成 markdown 文档

openapi-generator-cli generate \
    -i swagger.json \
    -g markdown \
    -o docs/markdown

8.4 生成 postman 集合

如果需要将接口导入 postman 进行调试，可以使用 postman-collection 生成器：

openapi-generator-cli generate \
    -i swagger.json \
    -g postman-collection \
    -o docs/postman

9. 自动化导出脚本实战

在实际项目中，我们通常希望将导出过程集成到 ci/cd 流水线中。下面给出一个完整的 shell 脚本示例，实现「拉取 openapi 描述文件 → 生成 markdown → 生成 html → 生成 pdf」的自动化流程。

#!/bin/bash
set -e
api_base_url="${api_base_url:-http://localhost:8080}"
output_dir="${output_dir:-./docs}"
token="${token:-}"
echo "开始导出 swagger 文档..."
mkdir -p "$output_dir"
1. 拉取 openapi 描述文件
echo "拉取 openapi 描述文件..."
if [ -n "$token" ]; then
curl -h "authorization: bearer $token" 
-o "$output_dir/swagger.json"
"$api_base_url/v3/api-docs"
else
curl -o "$output_dir/swagger.json"
"$api_base_url/v3/api-docs"
fi
2. 使用 widdershins 生成 markdown
echo "生成 markdown 文档..."
widdershins --language zh
--summary
--omitheader
--search false
"$output_dir/swagger.json"
-o "$output_dir/api-docs.md"
3. 使用 redoc-cli 生成 html
echo "生成 html 文档..."
redoc-cli bundle "$output_dir/swagger.json"
--title "api 文档"
-o "$output_dir/api-docs.html"
4. 使用 puppeteer 生成 pdf
echo "生成 pdf 文档..."
npx --yes puppeteer print-to-pdf
--landscape
--format a4
"$output_dir/api-docs.html"
"$output_dir/api-docs.pdf"
echo "文档导出完成，输出目录: $output_dir"
ls -lh "$output_dir"

在 jenkins 或 github actions 中，只需在构建步骤中调用该脚本即可。下面是一个 github actions 的示例片段：

name: export api docs
on:
push:
branches: [ main ]
jobs:
export-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g widdershins redoc-cli
- run: chmod +x export-docs.sh
- run: ./export-docs.sh
env:
api_base_url: https://api.example.com
token: ${{ secrets.api_token }}
- uses: actions/upload-artifact@v4
with:
name: api-docs
path: docs/

10. 常见问题与解决方案

10.1 导出的 markdown 中中文乱码

确保在转换时指定语言参数。使用 widdershins 时添加 --language zh，使用 swagger2markup 时设置 withoutputlanguage(language.zh)。同时确认源 openapi 描述文件中的 description 字段使用 utf-8 编码。

10.2 pdf 导出时内容被截断

这通常是因为页面宽度超出纸张范围。可以尝试使用横向布局（--landscape），或者调整 puppeteer 的页面缩放比例：

npx --yes puppeteer print-to-pdf \
    --landscape \
    --format a4 \
    --scale 0.8 \
    api-docs.html api-docs.pdf

10.3 接口需要登录认证

如果 swagger ui 页面本身需要登录，可以在拉取 openapi 描述文件时携带 cookie 或 token。对于 swagger ui 页面内的接口调试认证，可以在页面右上角的 authorize 按钮中配置，但这不影响文档导出。

10.4 导出的 html 文件过大

当接口数量较多时，生成的 html 文件可能达到几十 mb。可以通过 redoc-cli 的 --options.disablesearch 选项关闭搜索功能，减小文件体积：

redoc-cli bundle swagger.json \
    --options.disablesearch \
    -o api-docs.html

11. 总结

本文介绍了多种 swagger ui 导出文档的方案，从最简单的浏览器打印，到可集成 ci/cd 的自动化脚本，覆盖了 markdown、html、pdf、asciidoc 和 postman 集合等常见格式。在实际项目中，建议根据团队的技术栈和交付场景选择合适的方案：

需要离线交付或知识沉淀时，优先选择 markdown 或 asciidoc。
需要对外发布在线文档时，使用 redoc-cli 生成独立 html。
需要打印或归档时，使用 puppeteer 导出 pdf。
需要自动化集成时，将导出脚本接入 ci/cd 流水线。

希望本文的代码实例能够帮助你快速搭建起 swagger 文档导出能力，提升接口文档的维护效率。

到此这篇关于swagger ui 导出文档：从入门到实战的完整指南的文章就介绍到这了,更多相关swagger ui 导出文档内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

Swagger UI 导出文档从入门到实战指南

2026年08月17日 • Java •我要评论