Linux系统中Swagger如何实现API文档的导出

Linux下导出Swagger API文档的实用方法

一 前置说明与准备

• Swagger/OpenAPI 规范以 JSON/YAML 描述 API，导出通常指获取该规范文件或将其转换生成其他产物（如静态站点、客户端代码）。在 Linux 环境下，可通过本地下载、服务端点、命令行工具与 CI/CD 等方式完成。若使用 Spring Boot，常见获取规范端点为 /v2/api-docs（可按分组参数 ?group=分组名 导出），UI 通常位于 /swagger-ui.html。

二 常用导出方式

• 从 Swagger UI 直接下载

  • 打开部署的 Swagger UI，点击页面右上角的 Download 或 Download Swagger JSON，即可保存 swagger.json。若需 YAML，可先导出 JSON 再用工具转换（见下文）。适用于临时导出与快速分享。

• 从服务端点或网关导出 JSON

  • 直接请求规范端点获取 JSON，例如：
    • curl 示例：curl -o swagger.json http://localhost:8080/v2/api-docs?group=default
  • 多分组或网关聚合场景，按实际网关/服务提供的规范路径导出，再统一归档或转换。适合自动化脚本与流水线使用。

• 使用 Swagger Editor 导出或转换

  • 本地启动 Swagger Editor（Node.js 环境）：
    • 安装与启动：
      • sudo apt update && sudo apt install -y nodejs npm
      • 下载并解压 swagger-editor，进入目录后执行：npm install && npm run start
    • 在编辑器顶部菜单 File 中选择 Save as YAML 或 Convert and save as JSON，即可导出或互转 YAML/JSON。适合本地编辑与格式转换。

• 使用 OpenAPI Generator 生成静态文档或代码

  • 安装 CLI（Docker 方式示例）：
    • docker run --rm -v “$PWD:/local” openapitools/openapi-generator-cli generate
      -i /local/swagger.json -g html -o /local/api-docs-static
  • 常用生成器：html（静态站点）、html2（更友好的静态站点）、以及各类 client SDK。适合离线文档、门户托管与客户端代码生成。

• 使用 Swagger Codegen 生成文档或代码

  • 安装（Debian/Ubuntu 示例）：pip3 install swagger-codegen
  • 生成静态 HTML 文档：
    • swagger-codegen generate -i swagger.yaml -l swagger -o ./api-docs
  • 也可生成多语言客户端。适合已有 swagger.yaml 的存量项目。

三 进阶 生成PDF与CI/CD自动化

• 生成 PDF

  • Swagger UI 无内置 PDF 导出。可用浏览器“打印为 PDF”，或使用 Puppeteer 等无头浏览器将页面导出 PDF（示例命令：puppeteer --no-sandbox --print-to-pdf=api.pdf http://localhost:8080/swagger-ui.html）。适合对外发布版式固定的文档。

• 在 CI/CD 中自动导出与发布

  • 思路：在流水线中拉取规范（/v2/api-docs 或 swagger.yaml）、使用 openapi-generator-cli 生成 HTML 静态站点并发布到 Nginx 或对象存储；同时可把 JSON/YAML 归档到代码仓或 API 管理平台，实现版本化管理与批量导入。