Linux怎么整合Swagger

在 Linux 上“整合 Swagger”通常指 把 Swagger（OpenAPI）集成到你的后端项目里，用于接口文档生成和调试。不同语言/框架做法不一样，下面按 最常见的几种场景给你一个清晰、可落地的说明。

一、先明确：Swagger ≠ 一个软件

Swagger 现在叫 OpenAPI，常见组成：

组件	作用
swagger-core	生成接口描述
swagger-ui	可视化接口页面
OpenAPI 规范	接口描述标准

Linux 只是运行环境，重点在 你用的后端技术栈。

二、Java（Spring Boot）——最常见 ✅

1️⃣ 引入依赖（Maven）

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

✅ 推荐 springdoc-openapi（比 springfox 更新、稳定）

2️⃣ 启动项目

mvn spring-boot:run

3️⃣ 访问 Swagger UI

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

或

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

4️⃣ 接口示例

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

    @Operation(summary = "测试接口")
    @GetMapping("/test")
    public String test() {
        return "ok";
    }
}

三、Node.js（Express）

1️⃣ 安装依赖

npm install swagger-ui-express swagger-jsdoc

2️⃣ 配置 swagger

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API 文档',
      version: '1.0.0'
    }
  },
  apis: ['./routes/*.js']
};

const swaggerSpec = swaggerJsdoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

3️⃣ 访问

http://IP:3000/api-docs

四、Python（FastAPI ✅ 最省事）

FastAPI 自带 Swagger

pip install fastapi uvicorn

from fastapi import FastAPI

app = FastAPI()

@app.get("/test")
def test():
    return {"msg": "ok"}

启动：

uvicorn main:app --host 0.0.0.0 --port 8000

访问：

http://IP:8000/docs

五、Nginx + Swagger（静态 UI）

如果你只是 展示已有 OpenAPI 文档：

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

Nginx 配置：

server {
    location /swagger/ {
        root /opt/swagger-ui/dist;
        index index.html;
    }
}

修改 swagger.json 路径即可。

六、Linux 常见问题

❓ 访问不了 swagger-ui

✅ 检查：

firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

或云服务器安全组是否放行端口。

❓ 生产环境要不要开 Swagger？

✅ 建议：

开发 / 测试：开启
生产：关闭或加权限

（Spring 示例）

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

七、我可以继续帮你

你可以直接告诉我：

1️⃣ 后端语言（Java / Python / Node / Go）
2️⃣ 框架（Spring Boot / FastAPI / Express / Gin）
3️⃣ 是否需要 生产环境安全方案

我可以给你 完整可复制配置。