Debian Swagger如何支持API文档导出 - 问答

Debian环境下导出Swagger API文档的实用方案

一前置准备

更新系统并安装常用工具：sudo apt update && sudo apt install -y python3-pip nodejs npm。
选择并安装文档工具链：
- Node.js 生态：npm i -g swagger-jsdoc；服务端可用 swagger-ui-express 预览。
- Java/Spring 生态：使用 springfox 系列注解生成 /v2/api-docs；如需离线静态文件可用 swagger-codegen-cli 生成。
准备规范文件：至少维护一份 swagger.yaml 或 swagger.json（包含 openapi/swagger 版本、info、paths、definitions 等）。

二导出为JSON或YAML

从运行中的应用直接导出：若应用暴露 /v2/api-docs（Spring Boot 常见），使用 curl 保存：
curl http://localhost:8080/v2/api-docs > api-docs.json
如需 YAML，可本地转换：yq -P api-docs.json > api-docs.yaml（需安装 yq）。
从 Swagger Editor 或 SwaggerHub 导出：在编辑界面使用 File → Save as YAML / Convert and save as JSON，或在 SwaggerHub 右上角 Export 选择 JSON/YAML 下载。
备份与恢复：将 swagger.json/swagger.yaml 与导出的 api-docs.json 纳入版本控制或定期拷贝备份，便于回滚与审计。

三生成静态HTML或PDF

方案一静态HTML站点（Swagger UI 静态文件）
1. 下载 swagger-codegen-cli；2) 生成静态站点：
  java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l static -o /var/www/swagger-ui
2. 用 Nginx/Apache 托管生成的静态文件，适合离线浏览与归档。
方案二高质量离线文档（AsciiDoc/PDF）
1. 以 Spring Boot 为例，确保能访问 /v2/api-docs；
2. 使用 swagger2markup 将 OpenAPI 转为 AsciiDoc；
3. 再用 asciidoctor 生成 HTML5/PDF；
4. 可在构建脚本中配置字体与目录，解决中文乱码与多文件合并问题。

四一键脚本示例

导出 JSON + 生成静态 HTML（Node.js 项目示例）

#!/usr/bin/env bash
set -e
npm i -D swagger-jsdoc swagger-ui-express
npx swagger-jsdoc -i swagger.yaml -o ./docs/swagger.json
cat > ./docs/server.js <<'EOF'
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const spec = require('./swagger.json');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec, { customSiteTitle: 'API Docs' }));
app.listen(3000, () => console.log('Docs at http://localhost:3000/api-docs'));
EOF
node ./docs/server.js

执行后访问 http://localhost:3000/api-docs 预览，./docs/swagger.json 即为导出的规范文件。

五常见问题与建议

规范格式：确认使用 swagger: ‘2.0’ 或 openapi: 3.x，不同版本的 UI/生成器支持略有差异。
PDF 导出：Swagger UI 无内置 PDF，推荐“静态HTML站点”或“AsciiDoc→PDF”方案；浏览器“打印为PDF”仅适合临时查看。
中文与样式：生成 PDF 时配置中文字体与页眉页脚；静态站点可用自定义 CSS 优化打印样式。
版本控制：将 swagger.yaml/json 纳入 Git，导出产物（HTML/PDF）可放入 CI 的 artifacts 便于发布与回溯。

0 赞

0 踩