如何在CentOS上使用Swagger API

在CentOS上使用Swagger API的实用指南

一、常见方案与适用场景

• 使用 Swagger Editor 在本地或服务器上编写/编辑 OpenAPI/Swagger 规范（YAML/JSON），便于设计与协作。
• 使用 Swagger UI 托管文档页面，加载本地或远程的规范文件，提供可交互的 API 控制台。
• 在后端框架内集成文档生成（如 Spring Boot + Springfox/Swagger 2 或 OpenAPI 3），或 Node.js + swagger-jsdoc/swagger-ui-express，实现“代码即文档”。
• 直接用 Docker 运行 Swagger UI 容器，快速上线文档站点。以上方案均已在 CentOS 环境广泛实践。

二、方案一 快速托管Swagger UI并加载自定义规范

• 准备环境
  • 安装 Node.js（示例采用 Node.js 14.x）：
    • 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
• 部署 Swagger UI
  • 下载并起服务（示例目录 /opt/swagger）：
    • mkdir -p /opt/swagger && 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 -g http-server
    • http-server -p 3000
• 加载你的规范
  • 将你的 swagger.json/swagger.yaml 放到 swagger-ui-3.34.0/dist/（例如命名为 my-api.json）。
  • 编辑 dist/index.html，将默认 URL（如 petstore）替换为你的文件：
    • const specUrl = window.location.protocol + ‘//’ + window.location.hostname + ‘:’ + window.location.port + ‘/my-api.json’;
  • 访问：http://<服务器IP>:3000。如需外网访问，开放 TCP 3000 端口。

三、方案二 使用Docker运行Swagger UI

• 安装 Docker（若未安装）：
  • sudo yum install -y docker && sudo systemctl start docker && sudo systemctl enable docker
• 运行容器（将宿主机的 /opt/swagger 挂载到容器内 /usr/share/nginx/html，并指定你的规范）：
  • docker run -d –name swagger-ui -p 80:8080
    -v /opt/swagger:/usr/share/nginx/html
    swaggerapi/swagger-ui
• 将 swagger.json 放入 /opt/swagger，访问：http://<服务器IP>/<你的文件名>.json（容器默认服务端口为 8080，Nginx 代理到 80）。如需自定义页面标题、URL 等，可通过环境变量或挂载自定义配置。

四、在后端框架中集成文档生成

• Spring Boot 集成（Springfox，支持 Swagger 2）
  • 依赖示例（Maven）：
    • 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(“com.example.controller”))
      .paths(PathSelectors.any())
      .build();
      }
      }
  • 访问：http://<服务IP>:<端口>/swagger-ui.html（Springfox 2.x 默认路径）。
• Spring Boot 集成（Springdoc OpenAPI 3，推荐用于 Spring Boot 2.6+）
  • 依赖示例（Maven）：org.springdoc:springdoc-openapi-ui:1.7.x
  • 访问：http://<服务IP>:<端口>/swagger-ui.html（默认路径，自动扫描）。
• Node.js 集成（Express + swagger-jsdoc + swagger-ui-express）
  • 安装：npm i swagger-jsdoc swagger-ui-express
  • 代码示例：
    • const swaggerJsdoc = require(‘swagger-jsdoc’);
      const swaggerUi = require(‘swagger-ui-express’);
      const app = require(‘express’)();
      const options = {
      definition: {
      openapi: ‘3.0.0’,
      info: { title: ‘My API’, version: ‘1.0.0’ },
      servers: [{ url: ‘http://localhost:3000’, description: ‘Dev server’ }]
      },
      apis: [‘./routes/*.js’]
      };
      const specs = swaggerJsdoc(options);
      app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(specs));
      app.listen(3000, () => console.log(‘API docs at http://localhost:3000/api-docs’));
  • 访问：http://<服务器IP>:3000/api-docs。

五、常见问题与运维建议

• 跨域问题（CORS）
  • 若 Swagger UI 与后端 API 不同源，需在后端添加 CORS 头（如 Access-Control-Allow-Origin、Access-Control-Allow-Headers 等），或在开发环境使用代理。
• 安全与访问控制
  • 生产环境建议为文档站点加 认证/授权（如 Nginx 基本认证、反向代理鉴权、JWT 前置校验），避免未授权访问接口细节。
• 端口与防火墙
  • 确认 firewalld/安全组 已放行对应端口（如 3000、80、8080），否则外网无法访问。
• 规范版本与路径
  • 注意 Swagger 2.0 与 OpenAPI 3.0 的差异；不同版本的 UI 与后端库路径、配置项可能不同（如 Springfox 2.x 默认 /swagger-ui.html，Springdoc 默认 /swagger-ui.html）。
• 文档与实现一致性
  • 采用代码注解或工具从代码生成文档时，保持 注释/注解与实现同步，并通过 CI 校验规范文件的有效性。