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文档的自动生成、可视化与管理。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！