Centos Swagger如何集成

CentOS系统集成Swagger的完整流程

Swagger（现称OpenAPI）是一款用于设计、构建、文档化和使用RESTful Web服务的工具。在CentOS系统上集成Swagger，主要涉及环境准备、Swagger UI部署、后端应用集成及自动化管理等环节，以下是详细步骤：

一、准备工作

在集成Swagger前，需确保CentOS系统已更新，并安装必要的基础工具：

sudo yum update -y
sudo yum install -y wget curl git gcc-c++ make

二、安装Swagger UI（交互式文档界面）

Swagger UI是Swagger的核心组件，提供可视化的API文档浏览与测试功能。以下是三种常见部署方式：

1. 通过Node.js+NPM安装（推荐）

适用于需要灵活定制的场景，步骤如下：

安装Node.js和npm（JavaScript运行环境）：

curl -sL https://rpm.nodesource.com/setup_16.x | sudo bash -  # 使用Node.js 16版本（兼容性好）
sudo yum install -y nodejs

验证安装：

node -v  # 应输出v16.x.x
npm -v   # 应输出8.x.x及以上

下载并配置Swagger UI：

mkdir -p /opt/swagger && cd /opt/swagger
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.52.5.tar.gz  # 下载最新稳定版
tar -xzf v3.52.5.tar.gz --strip-components=1
mkdir -p ./public
cp -r ./dist/* ./public/  # 将Swagger UI静态文件复制到public目录

创建启动脚本（/opt/swagger/index.js）：

const express = require('express');
const app = express();
const path = require('path');

// 托管Swagger UI静态文件
app.use('/swagger', express.static(path.join(__dirname, 'public')));

// 自定义API文档入口（替换为你的实际文档路径）
app.get('/swagger', (req, res) => {
  res.sendFile(path.join(__dirname, 'public/index.html'));
});

// 启动服务（端口8080可自定义）
app.listen(8080, () => {
  console.log('Swagger UI is running at http://<your_server_ip>:8080/swagger');
});

启动Swagger UI服务：
```
cd /opt/swagger
npm install express  # 安装Express框架
node index.js
```
访问http://<your_server_ip>:8080/swagger，即可看到Swagger UI界面。

2. 使用Docker快速部署

适用于希望隔离环境、简化管理的场景：

# 拉取Swagger UI Docker镜像
sudo docker pull swaggerapi/swagger-ui

# 运行容器（映射端口8080到宿主机）
sudo docker run -d -p 8080:8080 \
  -e SWAGGER_FILE=/app/swagger.yaml \  # 指定API文档路径（需挂载卷）
  -v /opt/swagger/docs:/app \         # 挂载本地文档目录到容器
  --name swagger-ui swaggerapi/swagger-ui

# 访问Swagger UI
curl http://localhost:8080  # 应返回Swagger UI页面

3. 通过YUM仓库安装（CentOS 8+）

适用于追求简单快捷的场景（需确保系统已启用EPEL仓库）：

# 启用EPEL仓库
sudo dnf install -y epel-release

# 安装Swagger UI
sudo dnf install -y swagger-ui

# 启动服务（默认端口8080）
sudo systemctl start swagger-ui
sudo systemctl enable swagger-ui

# 访问Swagger UI
curl http://localhost:8080

三、后端应用集成Swagger（以Spring Boot为例）

若后端使用Spring Boot框架，可通过springfox-swagger组件自动生成API文档：

1. 添加Maven依赖

在项目的pom.xml中添加以下依赖：

<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>

2. 配置Swagger

创建Swagger配置类（如SwaggerConfig.java）：

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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理", description = "用户相关的CRUD操作")
public class UserController {

    @GetMapping
    @ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息")
    public String getUsers() {
        return "User list";
    }
}

4. 访问API文档

启动Spring Boot应用后，通过以下URL访问Swagger UI：

http://<your_server_ip>:8080/swagger-ui.html

即可看到自动生成的API文档，并支持在线测试。

四、自动化管理（可选）

为提升效率，可使用Jenkins等CI/CD工具自动化构建和部署：

// Jenkins Pipeline示例（Jenkinsfile）
pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git 'https://github.com/your-repo/your-spring-boot-app.git'
            }
        }
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
        stage('Deploy') {
            steps {
                sh 'java -jar target/your-app.jar &'
                sh 'cd /opt/swagger && node index.js &'
            }
        }
    }
}

每次代码提交后，Jenkins会自动构建应用、生成API文档并启动服务。

五、常见问题排查

端口冲突：若端口8080已被占用，可通过netstat -tulnp | grep 8080查看占用进程，或修改Swagger UI的启动端口。

防火墙限制：确保CentOS防火墙开放对应端口：

sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

中文乱码：在Swagger配置中添加produces = MediaType.APPLICATION_JSON_VALUE，或在Spring Boot中配置字符集：
```
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true
```

通过以上步骤，即可在CentOS系统上成功集成Swagger，实现API文档的自动生成、可视化与管理。