Swagger在Debian中的集成步骤是什么

Swagger在Debian中的集成步骤（以Spring Boot项目为例）

1. 环境准备

首先更新Debian系统软件包列表，并安装Java（Swagger运行的基础环境）、Maven（项目管理与构建工具）：

sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-11-jdk maven git
# 验证安装
java -version  # 确认Java版本（需11及以上）
mvn -version   # 确认Maven版本

2. 创建Spring Boot项目

通过Spring Initializr（https://start.spring.io/）生成基础Spring Boot项目，选择以下依赖：

Spring Web（提供RESTful API支持）；
Springfox Swagger2（旧版，兼容性好）或 Springdoc OpenAPI（新版，推荐，对应springdoc-openapi-starter-webmvc-ui）。
下载项目压缩包并解压到本地目录。

3. 添加Swagger依赖

进入项目根目录，编辑pom.xml文件（若使用Gradle则修改build.gradle）：

若使用Springdoc OpenAPI（推荐）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- 使用最新稳定版 -->
</dependency>

若使用传统Springfox Swagger2：

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

4. 配置Swagger

方式一：Springdoc OpenAPI（自动配置，无需额外类）

Springdoc OpenAPI无需手动编写配置类，只需在application.yml（或application.properties）中启用UI：

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html  # 可自定义路径（默认即可）
    operationsSorter: method  # 按HTTP方法排序（可选）

方式二：Springfox Swagger2（需手动配置类）

创建配置类（如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.controller")) // 替换为你的控制器包路径
                .paths(PathSelectors.any())
                .build();
    }
}

5. 编写API接口并添加注解

在controller包下创建REST控制器（如HelloController.java），使用Swagger注解描述接口：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
@Api(tags = "示例API", description = "基础CRUD操作接口") // 接口分类与描述
public class HelloController {

    @GetMapping("/hello")
    @ApiOperation(value = "问候接口", notes = "返回'Hello, World!'字符串", response = String.class)
    public String sayHello() {
        return "Hello, World!";
    }

    @PostMapping("/data")
    @ApiOperation(value = "数据提交接口", notes = "接收JSON字符串并返回确认信息")
    public String sendData(@RequestBody String data) {
        return "Received: " + data;
    }
}

6. 编译与打包项目

在项目根目录下执行Maven命令，生成可执行的JAR文件：

mvn clean package
# 打包完成后，JAR文件位于target目录（如demo-0.0.1-SNAPSHOT.jar）

7. 部署到Debian服务器

将生成的JAR文件传输到Debian服务器（使用scp命令）：

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

登录服务器，使用Java命令启动应用：

ssh user@your-server-ip
cd /opt/swagger-app/
java -jar demo-0.0.1-SNAPSHOT.jar
# 应用启动后，控制台会显示端口信息（默认8080）

8. 访问Swagger UI

在浏览器中输入以下URL访问Swagger文档：

Springdoc OpenAPI：http://your-server-ip:8080/swagger-ui.html
Springfox Swagger2：http://your-server-ip:8080/swagger-ui.html

进入页面后，可查看接口列表、输入参数、发送测试请求，并查看响应结果。

注意事项：

确保Spring Boot版本与Swagger依赖版本兼容（如Spring Boot 3.x推荐使用Springdoc OpenAPI 2.x）；
生产环境中，建议通过Spring Security限制Swagger UI的访问权限（如仅允许内网IP访问）；
若需自定义Swagger UI样式或功能，可修改src/main/resources/static目录下的静态文件（Springfox）或通过application.yml配置（Springdoc）。