在CentOS上使用Swagger生成API文档的完整流程
一、环境准备
在开始前，需确保CentOS系统已更新并安装必要工具：
sudo yum update -y
1. 安装Java环境（适用于Java/Spring Boot项目）
Swagger依赖Java运行，需安装OpenJDK 8：
sudo yum install -y java-1.8.0-openjdk-devel
java -version # 验证安装（需显示Java版本信息）
2. 安装Maven（用于Java项目构建）
Maven管理项目依赖及构建流程：
sudo yum install -y maven
mvn -version # 验证安装（需显示Maven版本信息）
3. 安装Node.js和npm（适用于Node.js项目）
若使用Node.js编写API，需安装Node.js和包管理工具npm：
curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -
sudo yum install -y nodejs
node -v # 验证Node.js版本
npm -v # 验证npm版本
4. 安装Docker（可选，快速部署Swagger UI）
通过Docker可快速启动Swagger UI，无需手动配置：
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
二、针对不同技术栈的具体步骤
场景1：Java/Spring Boot项目（常用）
1. 添加Swagger依赖
在项目的pom.xml（Maven）中添加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），指定API扫描的包路径：
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注解，描述API功能：
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") // 描述API模块
public class UserController {
@GetMapping("/users")
@ApiOperation("获取用户列表") // 描述接口功能
public String getUsers() {
return "用户列表数据";
}
}
4. 启动项目并访问Swagger UI
运行Spring Boot项目（mvn spring-boot:run），访问以下URL查看文档：
http://<服务器IP>:8080/swagger-ui.html
场景2：Node.js项目
1. 初始化Node.js项目
创建项目目录并初始化package.json：
mkdir my-node-api && cd my-node-api
npm init -y
2. 安装Swagger相关包
安装Express框架和Swagger UI中间件：
npm install express swagger-ui-express swagger-jsdoc
3. 配置Swagger文档
创建swagger.json（或swagger.yaml）文件，定义API基本信息和路径：
{
"openapi": "3.0.0",
"info": {
"title": "Node.js API文档",
"version": "1.0.0",
"description": "这是一个Node.js示例API"
},
"servers": [
{
"url": "http://localhost:3000",
"description": "本地开发服务器"
}
],
"paths": {
"/hello": {
"get": {
"summary": "获取问候信息",
"responses": {
"200": {
"description": "成功返回问候语",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
4. 集成Swagger到Express应用
创建app.js文件，将Swagger文档挂载到/api-docs路径：
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// 示例API路由
app.get('/hello', (req, res) => {
res.json({ message: "Hello, World!" });
});
app.listen(3000, () => {
console.log('Server running at http://localhost:3000');
});
5. 启动应用并访问文档
运行Node.js应用（node app.js），访问以下URL查看文档：
http://<服务器IP>:3000/api-docs
场景3：使用Docker快速部署Swagger UI
若不想手动配置，可使用Docker快速启动Swagger UI：
docker pull swaggerapi/swagger-ui
docker run -p 80:80 -d swaggerapi/swagger-ui
访问http://<服务器IP>即可查看Swagger UI，默认会尝试加载远程API文档（如petstore.swagger.io）。若需指向本地文档，可通过-e参数设置SWAGGER_FILE环境变量，或修改容器内的index.html文件。
三、自动化生成文档（可选）
1. Java项目：使用Swagger Maven插件
在pom.xml中添加插件，生成静态文档：
<build>
<plugins>
<plugin>
<groupId>io.swaggergroupId>
<artifactId>swagger-maven-pluginartifactId>
<version>2.1.9version>
<executions>
<execution>
<goals>
<goal>generategoal>
goals>
<configuration>
<outputDirectory>${project.build.directory}/generated-docsoutputDirectory>
<inputDirectory>${project.basedir}/src/main/javainputDirectory>
<language>javalanguage>
<generateApis>truegenerateApis>
<generateModels>truegenerateModels>
configuration>
execution>
executions>
plugin>
plugins>
build>
运行mvn clean package，生成的文档将存放在target/generated-docs目录。
2. Node.js项目：使用Swagger CLI
安装swagger-jsdoc命令行工具：
npm install -g swagger-jsdoc
通过命令生成文档：
swagger-jsdoc -i ./swagger-defs/*.js -o ./swagger.json
其中-i指定输入文件（如包含Swagger注释的JS文件），-o指定输出文件。
注意事项
- 安全性：生产环境中建议启用HTTPS，避免API文档泄露敏感信息。
- 版本兼容：确保Swagger依赖版本与项目技术栈兼容（如Spring Boot 2.x对应Swagger 2，Spring Boot 3.x对应Swagger 3/OpenAPI 3）。
- 文档维护：定期更新Swagger配置和注释，确保文档与API实际行为一致。
通过以上步骤，可在CentOS系统上快速生成并管理API文档，提升团队协作效率。
以上就是关于“如何使用CentOS Swagger生成API文档”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！
简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm