Linux上Swagger API文档如何生成离线版

Linux上生成Swagger离线版的可选方案

• 浏览器打印为PDF：直接在 Swagger UI 页面使用“打印为 PDF”，适合快速分享与归档。优点是简单、无需额外工具；缺点是样式与可定制性有限。
• 生成静态HTML站点：用 Redoc（单页、三栏、可搜索）或 OpenAPI Generator html2（多页站点）把 OpenAPI/Swagger JSON 转成可离线打开的 HTML。
• 生成PDF/Word：用 swagger2markup → Asciidoctor 流程产出 PDF/HTML，适合正式交付与打印。
• 内网离线托管：将 Swagger UI 静态资源与 swagger.json 一起放到 Nginx/Docker 中，在内网无外网依赖地浏览与分发。
• 一键工具：如 SwaggerOfflineDoc，支持导出 PDF/HTML5，适合 Spring Boot + Swagger2 项目快速出离线包。

准备OpenAPI规范文件

• 获取方式一：直接访问服务的 /v2/api-docs（Swagger 2.0）或 /v3/api-docs（OpenAPI 3.x）端点，保存为本地 swagger.json。
• 获取方式二：若项目集成了 springdoc-openapi-ui，默认 UI 路径为 /swagger-ui.html，其背后对应的 JSON 通常可通过 /v3/api-docs 获取。
• 获取方式三：若是 Go 项目并使用 swag，在项目根目录执行 swag init 生成 docs/（包含 swagger.json）。

方式一 浏览器打印为PDF

• 步骤：启动服务后打开 Swagger UI，按 Ctrl+P（或右键打印）→ 目标选择“另存为 PDF”→ 纸张选择 A4 或 横向 → 边距选“无”或“最小”→ 勾选“打印背景图形”（保留样式）→ 保存。
• 适用：临时分享、快速归档。
• 提示：若内容很长，建议分模块打印或使用更适合长文档的阅读器打开后再打印。

方式二 生成静态HTML站点

• 使用 Redoc（美观、单页、可搜索）
  1. 安装：npm i -g redoc-cli
  2. 从URL生成独立HTML：redoc-cli bundle https://petstore.swagger.io/v3/openapi.json -o redoc-static.html
  3. 从本地文件生成：redoc-cli bundle ./swagger.json -o redoc-static.html
  4. 预览：open redoc-static.html
• 使用 OpenAPI Generator（多页站点）
  1. 安装：npm i -g @openapitools/openapi-generator-cli
  2. 生成：openapi-generator-cli generate -i swagger.json -g html2 -o ./docs
  3. 预览：open ./docs/index.html
• 适用：需要离线浏览、可自定义主题、便于内网静态托管。

方式三 生成PDF或Word

• 使用 swagger2markup + Asciidoctor（推荐，适合正式交付）
  1. 安装：npm i -g swagger2markup-cli asciidoctor asciidoctor-pdf
  2. 从URL生成 AsciiDoc：swagger2markup convert -i http://localhost:8080/v2/api-docs -f swagger-doc
  3. 从本地JSON生成：swagger2markup convert -i ./swagger.json -f swagger-doc
  4. 生成PDF：asciidoctor-pdf swagger-doc.adoc -o swagger-doc.pdf
  5. 生成HTML：asciidoctor swagger-doc.adoc -o swagger-doc.html
• 使用 TableGo（面向非开发者，快速出 Word/Markdown）
  1. 打开 TableGo → 生成自定义文件 → Swagger
  2. 填入在线 api-docs 地址或选择本地 JSON 文件 → 设置 title/description
  3. 选择模块与模板 → 点击“生成Word离线API文档”或“生成Markdown”
• 适用：需要 PDF/Word 归档、对外交付、可模板化。

方式四 内网离线托管Swagger UI

• Docker Compose 示例（把 swagger.json 与 Swagger UI 静态资源一起托管）
  version: “3.8”
  services:
  swagger-ui:
  image: swaggerapi/swagger-ui
  environment:
  - SWAGGER_JSON=/app/docs/swagger.json
  ports:
  - “8080:8080”
  volumes:
  - ./docs:/app/docs
  启动：docker-compose up -d，访问 http://YOUR_IP:8080 即可离线浏览。
• 适用：内网环境、无外网依赖、统一访问入口与权限控制。