Swagger在Ubuntu上如何配置与部署

一、前提准备 在Ubuntu上配置Swagger前，需确保系统已更新并安装必要工具：

sudo apt update && sudo apt upgrade -y

二、安装Swagger核心工具 Swagger的配置与部署通常依赖swagger-jsdoc（生成文档）和swagger-ui-express（可视化界面），通过npm安装：

sudo apt install nodejs npm -y  # 安装Node.js和npm
sudo npm install -g swagger-jsdoc swagger-ui-express  # 全局安装Swagger工具

三、编写Swagger配置文件 创建swagger.yaml（或swagger.json）文件，定义API元数据（如路径、操作、模型）。示例如下：

swagger: '2.0'
info:
  title: Sample API
  description: A demo API for Swagger configuration on Ubuntu
  version: 1.0.0
host: localhost:3000
basePath: /api
schemes:
  - http
paths:
  /users:
    get:
      summary: Retrieve all users
      responses:
        '200':
          description: A list of user objects
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string

将文件保存至项目根目录（如/home/user/swagger-project/swagger.yaml）。

四、集成Swagger到Express应用

1. 初始化Node.js项目：

   mkdir swagger-project && cd swagger-project
   npm init -y
   

2. 安装Express及依赖：

   npm install express swagger-ui-express yamljs --save
   

3. 创建app.js文件，集成Swagger UI：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const YAML = require('yamljs');
   
   // 加载Swagger文档
   const swaggerDocument = YAML.load('./swagger.yaml');
   
   const app = express();
   // 将Swagger UI挂载至/api-docs路径
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   // 示例路由（需与swagger.yaml中的路径一致）
   app.get('/api/users', (req, res) => {
     res.json([{ id: 1, name: 'John Doe' }]);
   });
   
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => {
     console.log(`Server running at http://localhost:${PORT}`);
     console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
   });
   

五、启动应用并访问Swagger UI 运行Node.js应用：

node app.js

打开浏览器访问http://localhost:3000/api-docs，即可看到Swagger UI界面，展示API文档并支持交互式测试。

六、可选：使用Docker容器化部署 若需容器化部署，可按以下步骤操作：

1. 安装Docker：

   sudo apt install docker.io -y
   sudo systemctl start docker && sudo systemctl enable docker
   

2. 创建Dockerfile：

   FROM node:18
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   COPY . .
   EXPOSE 3000
   CMD ["node", "app.js"]
   

3. 构建并运行Docker容器：

   docker build -t swagger-ubuntu .
   docker run -p 3000:3000 -v $(pwd)/swagger.yaml:/app/swagger.yaml swagger-ubuntu
   

4. 访问http://localhost:3000/api-docs即可查看容器内的Swagger UI。

七、常见问题排查

• 端口冲突：若端口被占用，修改app.js中的PORT变量（如const PORT = 8080;）。
• 文件路径错误：确保swagger.yaml路径与YAML.load()中的路径一致。
• Docker权限问题：若无法访问容器内的文件，检查-v挂载路径是否正确。