Ubuntu Swagger如何与API集成

Ubuntu上Swagger与API集成的常见流程（以Express.js为例）

在Ubuntu系统中，Swagger（现多称为OpenAPI）与API集成的核心是通过Swagger UI工具实现API文档的可视化与测试。以下是具体步骤，适用于大多数基于Node.js的API项目：

1. 准备基础环境

首先确保系统安装了Node.js和npm（Node.js包管理器），这是集成Swagger的前提：

sudo apt update
sudo apt install nodejs npm

安装完成后，通过node -v和npm -v验证安装是否成功。

2. 初始化项目并安装Swagger依赖

创建一个新项目目录，初始化npm项目，并安装Swagger UI及配套工具：

mkdir my-api-project
cd my-api-project
npm init -y  # 初始化npm项目，生成package.json
npm install express swagger-ui-express yamljs --save  # 安装Express框架、Swagger UI及YAML解析工具

express：Node.js Web框架，用于构建API服务；
swagger-ui-express：将Swagger UI集成到Express应用中的中间件；
yamljs：用于解析YAML格式的Swagger文档（可选，也可使用JSON格式）。

3. 创建Swagger文档

在项目根目录下创建swagger.yaml（或swagger.json）文件，定义API的元数据、路径、参数及响应。示例如下：

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

此文档定义了一个/users接口，用于获取用户列表，并描述了返回数据的格式。

4. 集成Swagger UI到Express应用

在项目根目录下创建app.js文件，编写Express应用并集成Swagger UI：

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

const app = express();

// 加载Swagger文档
const swaggerDocument = YAML.load('./swagger.yaml');

// 集成Swagger UI，挂载到/api-docs路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 示例API路由（对应swagger.yaml中的定义）
app.get('/users', (req, res) => {
  res.json([
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
  ]);
});

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

swaggerUi.serve：提供Swagger UI的静态文件服务；
swaggerUi.setup(swaggerDocument)：将Swagger文档与UI绑定，生成交互式界面。

5. 运行应用并访问Swagger UI

启动Express应用：

node app.js

打开浏览器，访问http://localhost:3000/api-docs，即可看到Swagger UI界面。界面中会显示API的文档结构，点击/users接口可查看详情，并直接测试接口（无需编写客户端代码）。

可选：使用Docker集成Swagger

若不想在本地安装依赖，可使用Docker快速部署Swagger UI：

# 拉取Swagger UI Docker镜像
docker pull swaggerapi/swagger-ui

# 运行容器，挂载本地的swagger.yaml文件
docker run -p 8080:8080 -v $(pwd)/swagger.yaml:/app/swagger.yaml swaggerapi/swagger-ui

访问http://localhost:8080即可查看Swagger UI，容器会自动加载挂载的Swagger文档。

注意事项

若使用Spring Boot项目（Java），集成方式不同：需添加springfox-swagger2（Swagger 2）或springdoc-openapi-ui（OpenAPI 3）依赖，创建配置类并通过注解（如@Api、@ApiOperation）描述接口，访问/swagger-ui.html查看文档；
Swagger文档需与API实际接口保持一致，避免文档与实现不符；
生产环境中，建议关闭Swagger UI的调试功能，或限制访问权限。