ubuntu swagger如何集成

下面以 Ubuntu 环境为例，按常见场景给你讲 Swagger 的集成方式。Swagger 通常指 OpenAPI + Swagger UI，用于接口文档展示和调试。

一、常见集成方式选择

二、Ubuntu 上通用准备

sudo apt update
sudo apt install -y openjdk-17-jdk nginx nodejs npm python3-pip

三、Spring Boot 项目集成 Swagger（最常用）

1. 使用 springdoc-openapi（推荐）

添加依赖（Maven）

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

访问地址

http://localhost:8080/swagger-ui.html

接口示例

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

    @GetMapping("/users")
    public List<String> getUsers() {
        return List.of("Alice", "Bob");
    }
}

四、Node.js + Express 集成 Swagger

1. 安装依赖

npm init -y
npm install express swagger-ui-express yamljs

2. 示例代码

const express = require("express");
const swaggerUi = require("swagger-ui-express");
const YAML = require("yamljs");

const swaggerDocument = YAML.load("./swagger.yaml");
const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
  console.log("Swagger: http://localhost:3000/api-docs");
});

3. swagger.yaml 示例

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users
      responses:
        200:
          description: OK

五、Python FastAPI（最简单）

pip install fastapi uvicorn

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_users():
    return ["Alice", "Bob"]

启动：

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

访问：

http://<ubuntu-ip>:8000/docs

六、通过 Nginx 对外暴露（Ubuntu 常见）

server {
    listen 80;
    server_name api.example.com;

    location /swagger-ui/ {
        proxy_pass http://127.0.0.1:8080/;
    }
}

七、常见问题

✅ 端口访问不了

• 检查 Ubuntu 防火墙

sudo ufw allow 8080

✅ 生产环境建议

• 加鉴权（Basic Auth / OAuth）
• 不要直接暴露公网

八、我可以继续帮你

你可以告诉我：

• 用的是 Java / Node / Python / Go？
• 是否是 Spring Boot？
• 是否需要 生产级安全配置？

我可以直接给你 完整可运行示例。