Swagger在Debian中的部署步骤

Swagger在Debian中的部署步骤（三种常见方式）

一、基于Spring Boot项目（Java生态，最常用）

适用于已有Spring Boot后端服务的场景，通过添加Swagger依赖生成API文档。
1. 环境准备
更新系统并安装Java（JDK 11及以上）、Maven：

sudo apt update &
    &
     sudo apt upgrade -y
sudo apt install openjdk-11-jdk maven -y
# 验证安装
java -version  # 应显示Java版本信息
mvn -version   # 应显示Maven版本信息

2. 添加Swagger依赖
进入Spring Boot项目的pom.xml文件，添加以下依赖（以springfox-boot-starter为例，兼容Spring Boot 3.x）：

<
    dependency>
    
    <
    groupId>
    io.springfox<
    /groupId>
    
    <
    artifactId>
    springfox-boot-starter<
    /artifactId>
    
    <
    version>
    3.0.0<
    /version>
    
<
    /dependency>
    

3. 配置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.demo")) // 替换为你的控制器包名
                .paths(PathSelectors.any())
                .build();

    }

}
    

4. 打包与部署
使用Maven打包项目为可执行JAR：

mvn clean install

将生成的JAR文件（如target/demo-0.0.1-SNAPSHOT.jar）复制到Debian服务器，通过Java命令运行：

scp target/demo-0.0.1-SNAPSHOT.jar user@your-server-ip:/opt/swagger-app/
ssh user@your-server-ip
java -jar /opt/swagger-app/demo-0.0.1-SNAPSHOT.jar

5. 访问Swagger UI
在浏览器中输入服务器IP及端口（默认8080）：

http://your-server-ip:8080/swagger-ui.html

二、基于Express.js（Node.js生态，轻量级）

适用于需要快速搭建API文档的场景，无需Java环境。
1. 环境准备
安装Node.js（v14及以上）、npm及Swagger工具：

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g swagger-jsdoc swagger-ui-express

2. 创建Express应用
新建app.js文件，配置Swagger UI：

const express = require('express');
    
const swaggerUi = require('swagger-ui-express');
    
const swaggerDocument = require('./swagger.json');
     // 引入Swagger文档

const app = express();
    
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
     // 挂载Swagger UI到/api-docs路径

const PORT = process.env.PORT || 3000;
    
app.listen(PORT, () =>
 console.log(`Server running on port ${
PORT}
    `));

3. 编写Swagger文档
创建swagger.json文件，定义API规范（示例）：

{

  "swagger": "2.0",
  "info": {

    "title": "Sample API",
    "version": "1.0.0",
    "description": "A demo API for Swagger deployment"
  }
,
  "basePath": "/api",
  "paths": {

    "/users": {

      "get": {

        "summary": "Get all users",
        "responses": {

          "200": {

            "description": "A list of users"
          }

        }

      }

    }

  }

}
    

4. 启动应用
运行Express应用：

node app.js

5. 访问Swagger UI
在浏览器中输入：

http://your-server-ip:3000/api-docs

三、基于Docker（容器化，易扩展）

适用于需要隔离环境或快速迁移的场景。
1. 安装Docker
更新系统并安装Docker：

sudo apt update &
    &
     sudo apt upgrade -y
sudo apt install docker.io -y
sudo systemctl enable --now docker

2. 拉取Swagger UI镜像
从Docker Hub获取官方Swagger UI镜像：

docker pull swaggerapi/swagger-ui

3. 运行容器
映射端口（如8080）并启动容器：

docker run -d -p 8080:8080 --name swagger-ui swaggerapi/swagger-ui

4. 访问Swagger UI
在浏览器中输入：

http://your-server-ip:8080

注意事项

• 安全性：生产环境中建议关闭Swagger的公开访问（如Spring Boot中配置@EnableSwagger2的security属性），或添加认证机制。
• 版本兼容：Swagger依赖版本需与Spring Boot/Node.js版本匹配（如Spring Boot 3.x推荐springfox-boot-starter 3.0.0+）。
• 静态文件部署：若使用Docker或Nginx，可将Swagger UI静态文件（如dist/目录）复制到对应目录，通过Nginx反向代理提升性能。

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