SwaggerUI文档导出技巧大全

原创于 2025-10-30 07:45:00 发布 · 980 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#eureka

Swagger UI 导出文档的方法

Swagger UI 是一个用于可视化 RESTful API 文档的工具，但有时需要将其导出为离线文档（如 PDF、HTML 或 Markdown）以便分发或存档。以下是几种常见的导出方法。

使用 Swagger UI 自带的导出功能

Swagger UI 默认提供 JSON/YAML 格式的导出功能，但支持进一步转换为其他格式。

// 在 Swagger UI 的界面中，通常可以通过右上角的 "Export" 按钮下载 OpenAPI 规范文件
// 示例 Swagger 配置（swagger-config.json）：
{
  "urls": [
    {
      "name": "API v1",
      "url": "/api/v1/swagger.json"
    }
  ]
}

使用 Swagger2Markup 转换为 Markdown/AsciiDoc

Swagger2Markup 是一个库，可将 Swagger JSON 转换为可读性更强的 Markdown 或 AsciiDoc 文档。

// Maven 依赖
<dependency>
  <groupId>io.github.swagger2markup</groupId>
  <artifactId>swagger2markup</artifactId>
  <version>1.3.3</version>
</dependency>

// Java 代码示例
import io.github.swagger2markup.Swagger2MarkupConverter;
import java.nio.file.Paths;

public class SwaggerToMarkdown {
  public static void main(String[] args) {
    Swagger2MarkupConverter.from(Paths.get("swagger.json"))
      .build()
      .toFile(Paths.get("output"));
  }
}

使用 redoc-cli 生成静态 HTML

Redoc 是一个用于生成 API 文档的工具，支持从 OpenAPI 规范生成可部署的 HTML 文件。

# 安装 redoc-cli
npm install -g redoc-cli

# 生成 HTML 文档
redoc-cli bundle swagger.json -o api-docs.html

使用 wkhtmltopdf 将 HTML 转为 PDF

若需 PDF 格式，可通过 wkhtmltopdf 工具将 Swagger UI 生成的 HTML 转换为 PDF。

# 安装 wkhtmltopdf（Linux/macOS）
brew install wkhtmltopdf  # macOS
sudo apt-get install wkhtmltopdf  # Ubuntu

# 转换 HTML 至 PDF
wkhtmltopdf http://localhost:8080/swagger-ui.html swagger-docs.pdf

自定义脚本自动化导出

可通过 Node.js 脚本自动化导出流程。

const fs = require('fs');
const { exec } = require('child_process');

// 假设已生成 swagger.json
exec('redoc-cli bundle swagger.json -o docs.html', (error) => {
  if (error) console.error('导出失败:', error);
  else console.log('HTML 文档已生成');
});

以上方法可根据需求选择，适用于不同场景的文档导出需求。