swagger在ubuntu上部署步骤

在 Ubuntu 上部署 Swagger 的常用方式

使用容器快速起一个独立的 Swagger Editor 或 Swagger UI（适合演示、临时编辑与查看）。
将 Swagger UI 集成到 Node.js + Express 服务中（适合自有后端服务托管文档）。
在 Spring Boot 项目中启用 Swagger/OpenAPI（适合 Java 微服务自带文档页）。

方式一使用 Docker 快速部署 Editor 与 UI

安装 Docker（如未安装）
- 更新索引并安装：sudo apt update && sudo apt install -y docker.io
- 启动并设置开机自启：sudo systemctl start docker && sudo systemctl enable docker
运行容器
- Swagger Editor（编辑规范）：
  - 拉取并运行：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  - 访问：http://服务器IP:38080
- Swagger UI（展示规范）：
  - 拉取并运行：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
  - 访问：http://服务器IP:38081（首次进入可在页面中粘贴或指定你的 swagger.yaml/swagger.json 地址）
说明
- 上述为官方镜像的稳定版本示例，生产环境建议固定版本号并按需配置持久化与反向代理。

方式二在 Node.js + Express 中集成 Swagger UI

准备环境
- 安装 Node.js 与 npm：sudo apt update && sudo apt install -y nodejs npm
初始化项目并安装依赖
- 创建目录并初始化：mkdir swagger-demo && cd swagger-demo && npm init -y
- 安装中间件：npm install express swagger-ui-express yamljs

创建示例文件

新建 app.js：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml'); // 你的规范文件

const app = express();
const PORT = process.env.PORT || 3000;

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.get('/', (req, res) => res.send('API 文档：<a href="/api-docs">/api-docs</a>'));

app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

新建 swagger.yaml（示例片段）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /ping:
    get:
      summary: 健康检查
      responses:
        '200':
          description: OK

启动与访问
- 启动：node app.js
- 访问：http://服务器IP:3000/api-docs
说明
- 也可使用 swagger.json；如使用 swagger-jsdoc 可自动从代码注释生成规范。

方式三在 Spring Boot 项目中启用 Swagger

准备环境
- 安装 OpenJDK 11 与 Maven：sudo apt install -y openjdk-11-jdk maven

添加依赖（Maven，Spring Boot 2.x 常用 springfox）

在 pom.xml 中加入：

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

配置 Swagger

新建 SwaggerConfig.java：

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.controller"))
            .paths(PathSelectors.any())
            .build();
    }
}

运行与访问
- 构建：mvn clean package
- 运行：java -jar target/your-app.jar
- 访问：http://服务器IP:8080/swagger-ui.html
说明
- Spring Boot 3.x 建议使用 springdoc-openapi 替代 springfox，以获得更好的兼容性与维护度。

可选使用 Nginx 反向代理与对外发布

安装 Nginx：sudo apt install -y nginx

配置示例（/etc/nginx/sites-available/default）

server {
    listen 80;
    server_name your-domain.com;

    location /api-docs/ {
        proxy_pass http://127.0.0.1:3000/api-docs/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

校验与生效
- 校验：sudo nginx -t
- 重启：sudo systemctl restart nginx
说明
- 若部署在云服务器，请同时开放 80/443 端口并在 DNS 中解析到服务器 IP。

最新问答

相关标签