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 便于发布与回溯。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！