CentOS环境下Swagger集成方案汇总
在CentOS系统中集成Swagger（现多称为OpenAPI Specification，OAS），主要围绕环境准备、框架集成、文档生成与管理三个核心环节展开。以下是具体实施方案，覆盖Java Spring Boot、Node.js等常见技术栈：
一、基础环境准备
无论选择哪种集成方式，需先安装以下基础工具：
- Java环境（适用于Java项目）：Swagger依赖Java运行环境，通过以下命令安装OpenJDK 11：
sudo yum install -y java-11-openjdk-devel java -version # 验证安装（需显示11.x版本） - Maven（适用于Java项目）：用于项目构建与依赖管理：
sudo yum install -y maven mvn -version # 验证安装（需显示Maven版本） - Node.js与npm（适用于Node.js项目）：用于安装Swagger UI及相关工具：
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 # 验证安装（需显示14.x及以上版本） npm -v # 验证安装（需显示6.x及以上版本）
二、Java Spring Boot项目集成（常用方案）
适用于基于Spring Boot开发的Java应用，通过注解自动生成API文档。
1. 添加Swagger依赖
在项目的pom.xml文件中添加Swagger核心依赖：
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
2. 配置Swagger
创建Swagger配置类（如SwaggerConfig.java），启用Swagger并定义文档信息：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定Controller包路径
.paths(PathSelectors.any())
.build();
}
}
3. 添加API注解
在Controller类或方法上使用Swagger注解，丰富文档内容：
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(tags = "用户管理API") // 接口分类标签
public class UserController {
@GetMapping("/users")
@ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息")
public String getUsers() {
return "用户列表数据";
}
}
4. 启动应用并访问
启动Spring Boot应用后，通过以下URL访问Swagger UI：
http://<服务器IP>:8080/swagger-ui.html
即可看到自动生成的API文档，支持在线测试接口。
三、Node.js项目集成
适用于基于Express、Koa等框架的Node.js应用。
1. 安装Swagger工具
通过npm安装Swagger UI及生成器：
npm install -g swagger-ui-express swagger-jsdoc
2. 配置Swagger
创建Express应用并集成Swagger（如app.js）：
const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
const port = 3000;
// Swagger定义
const swaggerDefinition = {
openapi: '3.0.0',
info: {
title: 'Node.js API文档',
version: '1.0.0',
description: '基于Express的API文档'
},
servers: [{ url: `http://localhost:${port}`, description: '开发环境' }]
};
// 生成Swagger文档
const options = {
swaggerDefinition,
apis: ['./routes/*.js'] // 指向API路由文件路径
};
const swaggerSpec = swaggerJsdoc(options);
// 挂载Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.listen(port, () => {
console.log(`Server running at http://localhost:${port}`);
});
3. 编写API注释
在路由文件（如routes/user.js）中添加Swagger注释：
/**
* @swagger
* /users:
* get:
* tags: [用户管理]
* summary: 获取用户列表
* description: 返回所有用户的详细信息
* responses:
* 200:
* description: 请求成功
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
router.get('/users', (req, res) => {
res.json([{ id: 1, name: '张三' }, { id: 2, name: '李四' }]);
});
4. 启动应用并访问
启动Node.js应用后，通过以下URL访问Swagger UI：
http://<服务器IP>:3000/api-docs
四、Docker快速部署
适用于希望快速启动Swagger UI的场景，无需安装本地依赖。
1. 安装Docker
通过yum安装Docker并启动：
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
2. 拉取Swagger UI镜像
从Docker Hub拉取官方Swagger UI镜像：
docker pull swaggerapi/swagger-ui
3. 运行容器
将Swagger UI映射到宿主机80端口，指定API文档URL（如Swagger Hub或本地文件）：
docker run -d -p 80:8080 --name swagger-ui -e SWAGGER_FILE=https://petstore.swagger.io/v2/swagger.json swaggerapi/swagger-ui
若使用本地API文档（如swagger.yaml），可将文件挂载到容器中：
docker run -d -p 80:8080 -v /path/to/swagger.yaml:/app/swagger.yaml --name swagger-ui swaggerapi/swagger-ui
4. 访问Swagger UI
通过浏览器访问http://<服务器IP>，即可查看Swagger UI界面。
五、注意事项
- 生产环境安全：建议启用HTTPS（如通过Nginx配置SSL证书），避免API文档泄露。
- 文档同步：使用CI/CD工具（如Jenkins）在代码提交时自动生成和部署文档，确保文档与代码一致。
- 接口版本控制：通过Swagger的
tags或paths区分不同版本的API，便于维护。 - 中文乱码解决：若文档包含中文，需在Swagger配置中设置字符集（如Spring Boot中添加
spring.http.encoding.charset=UTF-8）。
以上方案覆盖了CentOS环境下Swagger的主要集成场景，可根据项目技术栈选择合适的方式。
以上就是关于“centos swagger集成方案”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！
简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm