怎么在Linux整合Swagger

在 Linux 上“整合 Swagger”通常取决于你使用的技术栈。下面我按最常见的几种场景给你一个清晰、可落地的说明，你可以直接对照使用。

一、先明确：Swagger 是什么？

Swagger 通常指：

Swagger UI：可视化接口文档页面
Swagger Editor：编写 OpenAPI 文件
Swagger 注解：在代码中自动生成接口文档

现在主流标准是 OpenAPI 3.x，工具链通常是：

springdoc-openapi（Spring Boot 推荐）
swagger-core（老项目）
或 直接写 YAML/JSON

二、最常见：Spring Boot + Swagger（Linux 通用）

1️⃣ 环境准备（Linux）

java -version
mvn -version

确保有 JDK 8+ 和 Maven / Gradle

2️⃣ 添加依赖（推荐 springdoc）

Maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

Gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

✅ 无需任何额外配置

3️⃣ 启动项目

mvn spring-boot:run

访问：

http://服务器IP:端口/swagger-ui/index.html

4️⃣ 使用注解生成文档

@RestController
@RequestMapping("/api")
public class UserController {

    @Operation(summary = "获取用户")
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "Tom");
    }
}

三、非 Spring Boot（如 Spring MVC）

1️⃣ 依赖

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

2️⃣ 配置类

@Configuration
@EnableOpenApi
public class SwaggerConfig {
}

访问：

/swagger-ui/index.html

⚠️ Springfox 已停止维护，不推荐新项目使用

四、纯 Linux + 静态 Swagger UI（无后端）

适合：

已有 OpenAPI YAML
只想展示接口文档

1️⃣ 下载 Swagger UI

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.0.zip
unzip v5.17.0.zip

2️⃣ 部署

cp -r swagger-ui-5.17.0/dist /var/www/html/swagger

3️⃣ 修改 API 地址

编辑：

/var/www/html/swagger/swagger-initializer.js

url: "http://你的IP/api/openapi.yaml"

浏览器访问：

http://服务器IP/swagger/

五、Docker 方式（Linux 推荐）

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api/openapi.yaml \
  -v $(pwd):/api \
  swaggerapi/swagger-ui

六、常见问题（Linux 环境）

❌ 访问不了 swagger-ui

检查：

firewall-cmd --list-ports
netstat -tunlp | grep 8080

❌ 权限问题

chmod -R 755 swagger-ui

七、我可以继续帮你

你可以直接告诉我：

✅ 用的是 Spring Boot / Node / Python / Go？
✅ 想要 自动生成 还是 手写 YAML？
✅ 是 内网部署 还是 生产环境？

我可以给你精确到版本的完整配置示例。