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。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！