在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 校验规范文件的有效性。
