centos swagger文档查看

在 CentOS 上查看 Swagger 文档的常用方式

• 使用 Docker 运行 Swagger Editor/UI（最省事，隔离环境、升级方便）
• 在 Node.js 项目内嵌 Swagger UI（适合已有 Node 服务）
• 在 Java Spring Boot 项目集成（Springfox，访问内置页面）
• 使用 静态文件托管 Swagger UI 并加载本地/远程 OpenAPI 文件（适合离线查看或托管第三方文档）

方式一 Docker 运行 Swagger Editor 和 Swagger UI

• 安装并启动 Docker（CentOS 7/8 常见做法）
  • 安装：sudo yum install -y docker
  • 启动并设置开机自启：sudo systemctl start docker & & sudo systemctl enable docker
• 拉取并运行容器
  • Swagger Editor（编辑 OpenAPI/Swagger 文件）
    • 运行：sudo docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
    • 访问：http://< 服务器IP> :38080
  • Swagger UI（展示文档）
    • 运行：sudo docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
    • 访问：http://< 服务器IP> :38081
• 提示
  • 如为云服务器，确保安全组/防火墙已放行 38080、38081 端口
  • 可将本地 OpenAPI 文件挂载到容器内，或在 UI 的页面中直接粘贴/选择文件

方式二 在 Node.js 项目内嵌 Swagger UI

• 安装依赖
  • sudo yum install -y gcc-c++ make
  • 安装 Node.js（示例为 Node.js 14.x）：
    • curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -
    • sudo yum install -y nodejs
• 启动 Swagger UI（两种常见做法）
  • 直接用官方 dist 目录托管
    • 下载并解压：wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz & & tar -xzf v3.34.0.tar.gz
    • 复制静态文件：mkdir -p /opt/swagger/public & & cp -r swagger-ui-3.34.0/dist/* /opt/swagger/public
    • 使用简单静态服务（需先 npm i -g http-server）：cd /opt/swagger/public & & http-server -p 3000
    • 访问：http://< 服务器IP> :3000
  • 在 Express 中集成
    • 安装：npm i express swagger-jsdoc swagger-ui-express
    • 示例代码（将 /api-docs 挂载到 Swagger UI）：

      • const express = require('express');
            
        const swaggerJsdoc = require('swagger-jsdoc');
            
        const swaggerUi = require('swagger-ui-express');
        
        
        const swaggerDefinition = {
        
          openapi: '3.0.0',
          info: {
         title: 'My API', version: '1.0.0' }
        ,
          servers: [{
         url: 'http://localhost:3000', description: 'Dev server' }
        ]
        }
            ;
        
        const options = {
         swaggerDefinition, apis: ['./routes/*.js'] }
            ;
            
        const swaggerSpec = swaggerJsdoc(options);
            
        
        const app = express();
            
        app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
            
        app.listen(3000, () =>
             console.log('Server on http://localhost:3000'));
            
        

    • 访问：http://< 服务器IP> :3000/api-docs
• 提示
  • 若需查看自定义 OpenAPI 文件，可将文件放到静态目录，并在 UI 页面把 URL 指向该文件

方式三 Java Spring Boot 集成 Swagger（Springfox）

• 引入依赖（Maven）

  • <
        dependency>
        
      <
        groupId>
        io.springfox<
        /groupId>
        
      <
        artifactId>
        springfox-swagger2<
        /artifactId>
        
      <
        version>
        2.9.2<
        /version>
        
    <
        /dependency>
        
    <
        dependency>
        
      <
        groupId>
        io.springfox<
        /groupId>
        
      <
        artifactId>
        springfox-swagger-ui<
        /artifactId>
        
      <
        version>
        2.9.2<
        /version>
        
    <
        /dependency>
    
    

• 配置类

  • @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
      @Bean
      public Docket api() {
        
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build();
    
      }
    
    }
        
    

• 启动应用后访问
  • 默认页面：http://< 服务器IP> :8080/swagger-ui.html
• 提示
  • 生产环境可按需限制路径与包扫描范围，避免暴露敏感接口

方式四 静态托管 Swagger UI 并加载自定义 OpenAPI 文件

• 准备文件
  • 将 Swagger UI 的 dist 目录 放到 Web 根目录（如 /var/www/swagger-ui/）
  • 将你的 openapi.json 或 swagger.yaml 放到同目录或指定静态目录
• 修改 Swagger UI 的 index.html
  • 找到 url 配置，改为你的文件地址（可为相对路径或完整 URL）
    • 例如：url: "openapi.json" 或 url: "https://api.example.com/openapi.json"
• 启动静态服务
  • Nginx/Apache 托管，或用 http-server：cd /var/www/swagger-ui & & http-server -p 3000
• 访问
  • http://< 服务器IP> :3000
• 适用场景
  • 离线查看第三方或历史版本的 API 文档
  • 统一托管多份规范文件并通过 Nginx 做鉴权/反向代理

常见问题与排查

• 无法访问页面
  • 检查防火墙/云安全组是否放行对应端口（如 3000、38080、38081、8080）
  • 本机测试可用 curl http://127.0.0.1:端口 验证服务是否监听
• 页面空白或报 404
  • 确认静态文件路径正确，Swagger UI 的 index.html 存在且可访问
  • 若使用容器，确认端口映射正确（-p 主机端口:容器端口）
• 跨域问题（浏览器控制台 CORS 报错）
  • 开发环境可在后端或网关开启 CORS；生产环境建议通过反向代理统一域名与端口
• 文档不显示或字段缺失
  • 确认 OpenAPI 文件格式正确（JSON/YAML 规范、必填字段完整）
  • Spring Boot 项目确认 Swagger 配置扫描到了目标包路径

以上方式可覆盖在 CentOS 上“查看 Swagger 文档”的主流场景，优先推荐使用 Docker 快速起服务，或与现有 Node/Java 项目集成以获得更好的开发体验。

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