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反向代理提升性能。