swagger在ubuntu的部署流程

Ubuntu 上部署 Swagger 的实用流程

一前置准备

更新系统并安装基础工具：
- 更新索引：sudo apt update && sudo apt upgrade -y
- 安装常用工具：sudo apt install -y curl
安装运行时（按项目选择其一或多项）：
- Node.js 与 npm（用于 Swagger UI/Editor、Node 项目集成）：
  - 推荐 LTS：curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
  - 安装：sudo apt install -y nodejs
  - 验证：node -v、npm -v
- OpenJDK 11（用于 Java 项目、部分代码生成工具）：
  - 安装：sudo apt install -y openjdk-11-jdk
  - 验证：java -version
可选：安装 Docker（用于容器化部署 Swagger UI/Editor）：
- 安装：sudo apt install -y docker.io
- 验证：sudo docker run hello-world。

二部署方式一 Docker 快速部署 Swagger UI

拉取镜像（两种常用镜像，二选一或都可用）：
- swaggerapi/swagger-ui-express（Node 基础）
- openapi/swagger-ui（官方 OpenAPI 版本）
准备规范文件：将 swagger.yaml 或 swagger.json 放到项目目录（如 /home/user/swagger-project/）。
运行容器（挂载规范文件并指定路径）：
- 示例（swaggerapi/swagger-ui-express）：
```
docker run -d -p 8080:8080 \
  -e SWAGGER_JSON=/app/swagger.yaml \
  -v $(pwd):/app \
  swaggerapi/swagger-ui-express
```
- 说明：
  - -d 后台运行；-p 8080:8080 端口映射
  - -e SWAGGER_JSON 指定容器内规范路径
  - -v $(pwd):/app 将当前目录挂载到容器 /app
访问文档：浏览器打开 http://localhost:8080（若远程服务器，替换为服务器 IP）。

三部署方式二 Node.js + Express 集成 Swagger UI

初始化项目并安装依赖：

mkdir swagger-node-app && cd $_
npm init -y
npm install express swagger-ui-express yamljs

创建规范文件 swagger.yaml（示例，OpenAPI 3.0）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
servers:
  - url: http://localhost:3000/api
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

创建服务入口 server.js：

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

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

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

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Swagger UI at http://localhost:${PORT}/api-docs`);
});

启动与访问：
- 启动：node server.js
- 访问：http://localhost:3000/api-docs。

四部署方式三在现有 Java Spring Boot 项目中集成

添加依赖（Maven，示例版本 2.9.2）：

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

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();
    }
}

启动应用并访问：
- 启动 Spring Boot（默认端口 8080）
- 访问：http://localhost:8080/swagger-ui.html（路径随版本/配置可能不同）。

五常用扩展与运维要点

反向代理与域名访问（Nginx 示例，将 /api-docs 代理到本地服务）：

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;
  }
}
sudo systemctl restart nginx

仅编辑文档时可部署 Swagger Editor（Docker）：
```
docker run -d -p 8081:8080 swaggerapi/swagger-editor
```
访问 http://localhost:8081 在线编辑并导出 swagger.yaml/json。

防火墙放行（如使用 ufw）：

sudo ufw allow 80,3000,8080,8081/tcp
sudo ufw enable

常见问题排查：
- 容器无法加载规范：确认 -v 挂载路径与 SWAGGER_JSON 容器内路径一致
- 页面空白或 404：检查服务是否监听 0.0.0.0、路径是否为 /api-docs 或 /swagger-ui.html
- 远程访问不了：云服务器需放行安全组/防火墙端口，Nginx/应用绑定到 0.0.0.0 而非 127.0.0.1。

最新问答

相关标签