centos swagger运行环境

CentOS 上搭建 Swagger 运行环境的实用方案

一 概念与组件选择

• Swagger/OpenAPI 是用于设计、文档化与调试 RESTful API 的工具链，常见组件包括：
  • Swagger Editor：在线/本地编辑 OpenAPI/Swagger 规范（YAML/JSON）。
  • Swagger UI：基于网页的文档与调试界面，可加载本地或远程的 spec 文件。
  • Swagger Core：Java 生态中生成与处理 API 文档的库（配合 Springfox 等使用）。
• 运行方式通常有两种：
  • 使用 Node.js 直接起服务（Editor/UI 静态文件托管 + 轻量服务）。
  • 使用 Java + Maven 构建，并通过 Tomcat 或 Nginx/Apache 发布。以上组件与路径选择可满足在 CentOS 上的常见部署需求。

二 方案一 Node.js 快速搭建 Editor 与 UI（推荐上手）

• 安装 Node.js 与 npm（示例为 Node.js 12.x 的仓库脚本，可按需调整版本）：
  • 安装编译工具与仓库脚本：sudo yum install -y gcc-c++ make && curl -sL https://rpm.nodesource.com/setup_12.x | bash -
  • 安装 Node.js：sudo yum install -y nodejs
  • 验证：node -v、npm -v
• 部署 Swagger Editor：
  • 准备目录：mkdir -p /opt/swagger && cd /opt/swagger
  • 下载并解压：wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz && tar -xf v3.14.0.tar.gz
  • 进入目录并启动：cd swagger-editor-3.14.0 && npm install -g http-server && http-server -p 8081
  • 访问：http://<服务器IP>:8081
• 部署 Swagger UI：
  • 下载并解压：cd /opt/swagger && wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz && tar -xf v3.34.0.tar.gz
  • 使用 Express 托管静态文件：
    • cd swagger-ui-3.34.0 && npm init -y && npm install express --save
    • mkdir public && cp -r swagger-ui-3.34.0/dist/* public/
    • 创建 index.js：

      const express = require('express');
      const app = express();
      app.use('/static', express.static('public'));
      app.get('/', (req, res) => res.send('Swagger UI'));
      app.listen(3000, () => console.log('UI listening on 3000'));
      

    • 启动：node index.js
  • 访问：http://<服务器IP>:3000/static/index.html
• 加载自定义文档：
  • 将编辑好的 swagger.json 放入 public，并修改 public/index.html 中的 url 为：/static/你的-swagger-file.json
  • 刷新页面即可展示自定义接口文档。

三 方案二 Java + Maven 构建并部署到 Tomcat

• 安装 OpenJDK 8 与 Maven：
  • sudo yum install -y java-1.8.0-openjdk-devel maven
  • 验证：java -version、mvn -version
• 构建并部署 Swagger UI：
  • 获取源码：git clone https://github.com/swagger-api/swagger-ui.git && cd swagger-ui
  • 构建：mvn clean package
  • 部署到 Tomcat（示例安装与发布）：
    • sudo yum install -y tomcat9-server tomcat9-admin
    • 复制构建产物：cp target/swagger-ui.war /var/lib/tomcat9/webapps/
    • 启动：sudo systemctl start tomcat9
  • 访问：http://<服务器IP>:8080/swagger-ui/index.html
• 说明：若使用 Spring Boot 项目，通常通过 springfox-swagger2 在应用内暴露 /v2/api-docs 与 /swagger-ui.html，无需额外部署 UI 包。

四 防火墙与访问、常见问题与最佳实践

• 防火墙放行端口（示例为 3000/8080/8081）：
  • sudo firewall-cmd --zone=public --add-port=3000/tcp --permanent
  • sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
  • sudo firewall-cmd --zone=public --add-port=8081/tcp --permanent
  • sudo firewall-cmd --reload
• 常见问题排查：
  • 访问不到页面：确认服务已启动、端口已放行、访问地址与端口正确（如 http://:3000/static/index.html）。
  • CORS 问题：在后端 API 开启跨域头（如 Access-Control-Allow-Origin: *），或将 UI 与 API 同源部署。
  • 路径 404：Swagger UI 静态资源路径为 /static/index.html（按实际部署路径调整）。
• 最佳实践：
  • 生产环境建议加 鉴权/反向代理（Nginx/Apache），并限制可访问来源。
  • 文档与实现保持同步，使用 Editor 校验规范，减少手工错误。
  • 静态资源启用 缓存与压缩，提升加载速度。