CentOS上Swagger API文档生成步骤

CentOS上Swagger API文档生成步骤

一 准备环境

• 更新系统并安装基础工具：
  • sudo yum update -y
  • sudo yum install -y curl wget unzip
• 安装 Node.js 与 npm（用于 Swagger Editor/UI 或 Node 服务）：
  • sudo yum install -y gcc-c++ make
  • curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -
  • sudo yum install -y nodejs
  • 验证：node -v 与 npm -v
• 如需使用 Docker 部署（可选）：
  • sudo yum install -y docker
  • sudo systemctl start docker && sudo systemctl enable docker
• 如需 Apache 静态托管（可选）：
  • sudo yum install -y httpd mod_ssl
  • sudo systemctl start httpd && sudo systemctl enable httpd 以上步骤为后续安装 Swagger Editor/UI 与部署文档提供基础运行环境。

二 方式一 使用 Swagger Editor 编写 OpenAPI 规范

• 准备目录并下载编辑器：
  • mkdir -p /opt/swagger && cd /opt/swagger
  • wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.14.0.tar.gz
  • tar -xzf v3.14.0.tar.gz && cd swagger-editor-3.14.0
• 启动服务（使用 http-server 便于快速预览）：
  • npm install -g http-server
  • http-server -p 8081 -c-1
• 访问与编写：打开浏览器访问 http://<服务器IP>:8081，在编辑器中编写 OpenAPI 3.0/2.0 的 YAML/JSON 规范，保存为本地文件（如 api.yaml 或 swagger.json）。

三 方式二 使用 Swagger UI 展示文档

• 下载并部署 UI 静态文件：
  • cd /opt/swagger
  • wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.34.0.tar.gz
  • tar -xzf v3.34.0.tar.gz && cd swagger-ui-3.34.0
  • npm install express --save
  • mkdir -p public && cp -r dist/* public/
• 自定义展示的规范文件（关键步骤）：
  • 将第“二”步生成的 api.yaml/swagger.json 放到 public/（如 public/api.yaml）
  • 编辑 public/index.html，找到 url 配置项，改为你的规范文件地址：
    • 例如：url: ‘/static/api.yaml’（若通过 static 路由访问）
• 启动服务：
  • node index.js
• 访问：打开 http://<服务器IP>:3000 查看并测试接口（UI 会自动加载 public 下的规范文件）。

四 方式三 在现有后端服务中集成生成与展示

• Node.js Express 集成（使用 swagger-jsdoc + swagger-ui-express）

  • 安装依赖：npm i swagger-jsdoc swagger-ui-express
  • 最小配置示例（app.js）：
    • const express = require(‘express’);
    • const swaggerJsdoc = require(‘swagger-jsdoc’);
    • const swaggerUi = require(‘swagger-ui-express’);
    • const app = express();
    • const swaggerDefinition = { openapi: ‘3.0.0’, info: { title: ‘My API’, version: ‘1.0.0’ }, servers: [{ url: ‘http://localhost:3000’ }] };
    • const options = { swaggerDefinition, apis: [‘./routes/*.js’] };
    • const swaggerSpec = swaggerJsdoc(options);
    • app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerSpec));
    • app.listen(3000, () => console.log(‘Server on :3000’));
  • 在路由文件使用注释编写规范（示例）：
    • /**
      • • @swagger
      • • /users:
      • • get:

      • • summary: 获取用户列表
          

      • • responses:
          

      • •   200:
          

      • •     description: 成功
          

      • •     content:
          

      • •       application/json:
          

      • •         schema:
          

      • •           type: array
          

      • •           items:
          

      • •             $ref: '#/components/schemas/User'
          

      • */
  • 访问：启动后在 http://<服务器IP>:3000/api-docs 查看文档。

• Java Spring Boot 集成（使用 springfox-swagger2/springfox-swagger-ui）

  • Maven 依赖（示例版本 2.9.2）：
    • - io.springfox - springfox-swagger2 - 2.9.2 -
    • - io.springfox - springfox-swagger-ui - 2.9.2 -
  • 配置类示例：
    • @Configuration
    • @EnableSwagger2
    • public class SwaggerConfig {
      • @Bean
      • public Docket api() {
        • return new Docket(DocumentationType.SWAGGER_2)
          • .select()
          • .apis(RequestHandlerSelectors.basePackage(“cn.weijishu.server.api.rest”))
          • .paths(PathSelectors.any())
          • .build();
        • }
      • }
  • 访问：启动后在 http://<服务器IP>:8080/swagger-ui.html 查看文档。

五 部署与安全加固

• 使用 Docker 快速托管 Swagger UI（适合演示与隔离环境）

  • 拉取镜像：docker pull swaggerapi/swagger-ui
  • 运行容器（将 /opt/swagger/public 挂载到容器内 /usr/share/nginx/html，并指定你的规范文件）：
    • docker run --name swagger-ui -d -p 80:8080 -v /opt/swagger/public:/usr/share/nginx/html swaggerapi/swagger-ui
  • 访问：打开 http://<服务器IP>/，在 UI 的 “URL” 中填入 /api.yaml 或 /swagger.json 即可加载你的规范。

• 使用 Apache 托管静态 UI 与规范文件

  • 将 UI 文件复制到 /var/www/html/swagger-ui，将 api.yaml 放到同目录
  • 配置虚拟主机（示例）：
    • <VirtualHost *:80>
      • ServerName your_server_ip_or_domain
      • DocumentRoot /var/www/html/swagger-ui
      • <Directory /var/www/html/swagger-ui>
        • Require all granted
  • 重启服务：sudo systemctl restart httpd
  • 访问：打开 http://<服务器IP>/swagger-ui/index.html，在 UI 中设置 URL 为 /api.yaml。

• 安全与运维建议

  • 生产环境启用 HTTPS（证书可用 Let’s Encrypt），并限制访问来源（防火墙/安全组仅放通必要 IP 与端口）
  • 规范文件与 UI 分离部署，UI 仅读取已发布的 JSON/YAML；必要时增加 Basic Auth/Nginx 鉴权
  • 规范文件纳入版本控制，变更通过 CI/CD 自动部署与回滚
  • 对外文档隐藏内部接口与敏感参数，使用 servers 区分 dev/staging/prod 环境地址