Centos Swagger如何部署应用

CentOS环境下Swagger应用部署指南

一、基础环境准备

在CentOS上部署Swagger应用前，需安装以下基础依赖：

1. Java环境：Swagger依赖Java运行环境（推荐OpenJDK 8），通过以下命令安装：

   sudo yum install -y java-1.8.0-openjdk-devel
   java -version  # 验证安装（需显示Java版本信息）
   

2. Maven：用于项目构建与依赖管理，安装命令：

   sudo yum install -y maven
   mvn -version  # 验证安装（需显示Maven版本信息）
   

3. Node.js与npm：若通过npm方式部署Swagger UI，需安装Node.js（建议版本12+）：

   curl -sL https://rpm.nodesource.com/setup_12.x | sudo bash -
   sudo yum install -y nodejs
   node -v  # 验证安装（需显示Node.js版本信息）
   npm -v   # 验证安装（需显示npm版本信息）
   

二、Swagger应用部署方式

方式1：Spring Boot项目集成Swagger（Java应用常用）

若需将Swagger集成到Spring Boot应用中，实现API文档自动化生成，步骤如下：

1. 添加Swagger依赖：在项目的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：创建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.yourpackage.controller")) // 替换为你的控制器包路径
                   .paths(PathSelectors.any())
                   .build();
       }
   }
   

3. 启动应用并访问：运行Spring Boot应用（mvn spring-boot:run），访问http://<服务器IP>:<应用端口>/swagger-ui.html（如http://192.168.1.100:8080/swagger-ui.html），即可查看Swagger UI界面。

方式2：Docker部署Swagger Editor/UI（快速搭建）

若需快速搭建Swagger编辑器或UI服务，可使用Docker：

1. 安装Docker：

   sudo yum install -y docker
   sudo systemctl start docker
   sudo systemctl enable docker
   

2. 部署Swagger Editor：

   docker pull swaggerapi/swagger-editor
   docker run -d -p 8080:8080 --name swagger-editor swaggerapi/swagger-editor
   

   访问http://<服务器IP>:8080，即可使用Swagger Editor编写API文档。
3. 部署Swagger UI：

   docker pull swaggerapi/swagger-ui
   docker run -d -p 8081:8081 --name swagger-ui swaggerapi/swagger-ui
   

   访问http://<服务器IP>:8081，默认会加载https://petstore.swagger.io/v2/swagger.json，可通过修改配置指向自定义API文档。

方式3：传统方式安装Swagger UI（手动部署）

若需手动部署Swagger UI，步骤如下：

1. 下载Swagger UI：

   mkdir -p /opt/swagger
   cd /opt/swagger
   wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
   tar -xf v3.34.0.tar.gz
   cd swagger-ui-3.34.0
   

2. 配置Swagger UI：
   • 复制dist目录内容到Web服务器目录（如Nginx的/usr/share/nginx/html）：

     sudo cp -r dist/* /usr/share/nginx/html/
     

   • 修改index.html文件，将默认的API文档URL（https://petstore.swagger.io/v2/swagger.json）替换为你的自定义URL（如http://<服务器IP>:<应用端口>/v2/api-docs）。
3. 启动Web服务器：若使用Nginx，启动服务：

   sudo systemctl start nginx
   sudo systemctl enable nginx
   

   访问http://<服务器IP>，即可查看Swagger UI界面。

三、自定义配置与安全

1. 自定义Swagger UI：可通过修改application.properties或application.yml文件调整Swagger UI行为，例如：

   springfox.documentation.swagger.v2.path=/v2/api-docs  # API文档路径
   springfox.documentation.swagger-ui.base-url=/swagger-ui.html  # UI入口路径
   

2. 安全配置：生产环境中，需限制Swagger UI访问权限（如仅允许内部IP访问），可通过Spring Security配置：

   import org.springframework.context.annotation.Configuration;
   import org.springframework.security.config.annotation.web.builders.HttpSecurity;
   import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
   
   @Configuration
   public class SecurityConfig extends WebSecurityConfigurerAdapter {
       @Override
       protected void configure(HttpSecurity http) throws Exception {
           http.authorizeRequests()
               .antMatchers("/swagger-ui.html", "/v2/api-docs").hasIpAddress("192.168.1.0/24")  # 仅允许192.168.1.0/24网段访问
               .anyRequest().permitAll()
               .and()
               .csrf().disable();
       }
   }
   

四、常见问题排查

1. 端口未开放：若无法访问Swagger UI，需检查CentOS防火墙是否开放对应端口（如8080、8081）：

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

2. Java环境问题：若启动应用时报Java版本错误，需确认JAVA_HOME环境变量是否正确设置：

   export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk
   export PATH=$JAVA_HOME/bin:$PATH
   

3. 依赖冲突：若Maven构建失败，需检查pom.xml中的依赖版本是否兼容（如Spring Boot与Swagger版本匹配）。

通过以上步骤，可在CentOS环境下完成Swagger应用的部署与配置，实现API文档的自动化管理与可视化测试。