OneAPI开源网关教程：API文档自动生成+Swagger UI集成配置

你是不是也遇到过这样的烦恼？团队里接入了各种大模型API，OpenAI、Claude、文心一言、通义千问……每个模型的调用方式都不一样，文档分散在各个平台，新同事上手要花好几天时间熟悉。更头疼的是，API接口文档更新不及时，前端开发同学总是来问：“这个参数到底怎么传？”

今天我要分享的解决方案，能让你用一个统一的接口访问所有主流大模型，更重要的是，它能自动生成清晰、规范的API文档，并集成Swagger UI，让接口调试和团队协作变得无比简单。

1. 什么是OneAPI？为什么你需要它？

简单来说，OneAPI是一个开源的LLM API管理和分发系统。它的核心价值可以用一句话概括：通过标准的OpenAI API格式，访问所有主流大模型。

想象一下，你团队里同时用着ChatGPT写代码、Claude分析文档、文心一言做中文内容生成。以前你需要：

  • 为每个模型单独申请API Key
  • 学习不同的调用方式
  • 处理不同的计费规则
  • 维护多套代码逻辑

现在有了OneAPI，你只需要：

  1. 部署一个OneAPI服务
  2. 把所有模型的API Key配置进去
  3. 用统一的OpenAI格式调用所有模型

更棒的是，OneAPI还提供了完整的API文档自动生成和Swagger UI集成。这意味着：

  • 前端同学可以直接在网页上测试接口
  • 新同事能快速了解所有可用接口
  • 接口变更时文档自动更新
  • 减少沟通成本，提升开发效率

2. 快速部署：10分钟搭建你的统一API网关

2.1 环境准备

OneAPI的部署非常简单，支持多种方式。我们先从最常用的Docker部署开始。

系统要求：

  • Linux/Windows/macOS都可以
  • Docker和Docker Compose
  • 至少1GB内存
  • 网络能访问外网（用于拉取模型API）

如果你还没有安装Docker，可以先用这个命令检查：

# 检查Docker是否安装
docker --version

# 检查Docker Compose是否安装
docker-compose --version

如果显示版本号，说明已经安装好了。如果没有安装，可以去Docker官网下载对应系统的安装包。

2.2 一键部署（Docker方式）

这是最简单的部署方式，适合大多数场景。创建一个docker-compose.yml文件：

version: '3.8'

services:
  oneapi:
    image: justsong/one-api:latest
    container_name: one-api
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - SQL_DSN=sqlite:///data/oneapi.db
      - REDIS_CONN_STRING=redis://redis:6379
      - SESSION_SECRET=your_session_secret_here
    restart: unless-stopped
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    container_name: one-api-redis
    restart: unless-stopped
    volumes:
      - ./redis-data:/data

保存文件后，只需要一行命令：

# 启动服务
docker-compose up -d

# 查看日志，确认服务正常启动
docker-compose logs -f oneapi

看到类似下面的输出，说明启动成功了：

one-api  | 2024/01/01 12:00:00 One API 启动成功
one-api  | 2024/01/01 12:00:00 监听端口: 3000

2.3 初次登录和配置

服务启动后，打开浏览器访问 http://你的服务器IP:3000，你会看到登录页面。

重要安全提醒： 使用root用户初次登录系统后，务必立即修改默认密码 123456！

登录后的操作流程：

  1. 点击右上角用户头像 → "修改密码"
  2. 输入旧密码 123456，设置一个强密码
  3. 确认修改，重新登录

现在你的OneAPI服务已经运行起来了。但要让它能真正工作，我们还需要配置模型渠道。

3. 配置模型渠道：接入所有主流大模型

OneAPI最强大的功能就是支持数十种主流大模型。我们来看看怎么配置。

3.1 添加第一个模型渠道（以OpenAI为例）

  1. 登录OneAPI管理后台
  2. 点击左侧菜单"渠道" → "添加渠道"
  3. 填写渠道信息：

基础信息：

  • 渠道名称：OpenAI官方
  • 渠道类型：选择"OpenAI"
  • 模型：填写"gpt-3.5-turbo,gpt-4,gpt-4-turbo"（用英文逗号分隔）
  • 分组：默认分组

认证信息：

  • API Key：填写你的OpenAI API Key（以sk-开头）
  • 代理地址（可选）：如果你需要代理，填写代理地址

高级设置：

  • 权重：默认100（用于负载均衡）
  • 并发数：根据你的需求设置
  • 自动禁用：开启后，如果连续失败会自动禁用该渠道

点击"提交"，你的第一个模型渠道就添加成功了。

3.2 批量添加其他模型

OneAPI支持批量添加渠道，这对于管理多个API Key特别方便。

  1. 准备一个CSV文件，格式如下：
名称,类型,密钥,模型,分组,权重,代理
OpenAI官方,OpenAI,sk-xxx,gpt-3.5-turbo,默认,100,
Claude官方,Anthropic,sk-ant-xxx,claude-3-opus,默认,100,
文心一言,百度文心一言,xxx,ERNIE-Bot,默认,100,
通义千问,阿里通义千问,xxx,qwen-turbo,默认,100,
  1. 在渠道页面点击"批量创建"
  2. 上传CSV文件，系统会自动创建所有渠道

3.3 测试渠道是否正常

添加完渠道后，需要测试一下是否配置正确：

# 使用curl测试OpenAI渠道
curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的OneAPI令牌" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

如果返回类似下面的响应，说明配置成功：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gpt-3.5-turbo",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好！有什么我可以帮助你的吗？"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

4. API文档自动生成：告别手动维护文档的烦恼

配置好模型渠道后，OneAPI会自动为所有接口生成完整的API文档。这是怎么做到的呢？

4.1 理解OneAPI的API结构

OneAPI的API设计完全兼容OpenAI官方API，这意味着：

  • 接口路径相同（如/v1/chat/completions）
  • 请求参数相同
  • 响应格式相同
  • 错误码相同

这种设计带来了巨大的好处：任何兼容OpenAI API的客户端，都能无缝接入OneAPI。

4.2 查看自动生成的API文档

OneAPI内置了API文档生成功能。访问以下地址可以看到：

  1. OpenAPI规范文档：http://localhost:3000/swagger/doc.json
  2. ReDoc文档：http://localhost:3000/redoc
  3. Swagger UI：http://localhost:3000/swagger

这些文档是实时自动生成的，基于你的实际配置。当你添加新的模型渠道或修改接口配置时，文档会自动更新。

4.3 API文档包含哪些内容？

自动生成的文档会包含：

接口列表：

  • 聊天补全接口 (/v1/chat/completions)
  • 模型列表接口 (/v1/models)
  • 余额查询接口 (/dashboard/billing/credit_grants)
  • 图像生成接口 (/v1/images/generations)
  • 语音转文字接口 (/v1/audio/transcriptions)

每个接口的详细信息：

  • 请求方法（GET/POST等）
  • 请求路径
  • 请求头要求
  • 请求参数（类型、是否必需、描述）
  • 响应示例
  • 错误码说明

认证信息：

  • Bearer Token的使用方式
  • 如何获取和管理Token

5. Swagger UI集成：可视化调试你的API

Swagger UI是一个强大的API文档和测试工具。OneAPI已经内置了Swagger UI，开箱即用。

5.1 访问Swagger UI

在浏览器中打开：http://localhost:3000/swagger

你会看到一个漂亮的交互式API文档界面，左侧是接口列表，右侧是接口详情和测试工具。

5.2 使用Swagger UI测试接口

我们以测试聊天接口为例：

  1. 找到 /v1/chat/completions 接口，点击展开
  2. 点击"Try it out"按钮
  3. 在请求体中填写测试数据：
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "用Python写一个快速排序算法"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}
  1. 点击"Execute"按钮
  2. 查看响应结果和状态码

Swagger UI的优势：

  • 无需安装额外工具：直接在浏览器中测试
  • 自动填充参数：不用手动写JSON
  • 实时查看响应：立即看到API返回结果
  • 支持认证：可以设置Authorization头
  • 导出请求：生成curl命令或代码片段

5.3 配置Swagger UI（可选）

OneAPI的Swagger UI支持一些自定义配置。你可以在环境变量中设置：

# docker-compose.yml中的环境变量
environment:
  - SWAGGER_HOST=api.yourdomain.com  # 设置Swagger显示的host
  - SWAGGER_BASE_PATH=/v1            # 设置基础路径
  - SWAGGER_SCHEMES=https            # 设置协议

6. 实际应用场景：团队协作的最佳实践

现在你已经部署好了OneAPI，配置了模型渠道，也了解了API文档功能。我们来看看在实际团队协作中，这些功能怎么用起来。

6.1 场景一：新同事快速上手

问题：新来的后端工程师需要调用大模型API，但不知道有哪些接口可用，参数怎么传。

解决方案：

  1. 给他Swagger UI地址：http://your-oneapi-domain/swagger
  2. 让他自己浏览所有可用接口
  3. 直接在页面上测试接口，查看响应格式
  4. 导出curl命令或代码片段，直接用在项目里

节省的时间：至少2-3天的文档查阅和调试时间。

6.2 场景二：前端后端联调

问题：前端同学需要调用大模型接口，但不确定请求格式和响应结构。

解决方案：

  1. 后端在OneAPI中配置好所有模型渠道
  2. 前端访问Swagger UI，查看接口文档
  3. 在Swagger UI中测试接口，确认参数和响应
  4. 根据测试结果调整前端代码

好处：减少沟通成本，避免因为参数格式问题反复调试。

6.3 场景三：API版本管理和文档同步

问题：API有更新时，文档没有及时更新，导致调用方使用旧的接口格式。

解决方案： OneAPI的文档是自动生成的，基于实际的接口实现。这意味着：

  • 接口有更新时，文档自动更新
  • 不会出现文档和实际接口不一致的情况
  • 所有调用方都能看到最新的接口规范

6.4 场景四：多模型统一管理

问题：项目中使用多个大模型，每个模型的调用方式都不一样。

解决方案： 通过OneAPI的统一接口：

  • 所有模型都用同样的OpenAI格式调用
  • 只需要维护一套代码逻辑
  • 切换模型时只需要改model参数
  • 在Swagger UI中可以看到所有支持的模型

7. 高级功能：让API管理更强大

OneAPI除了基本的API管理和文档生成，还提供了很多高级功能，让你的API网关更加强大。

7.1 负载均衡和故障转移

当你有多个相同模型的API Key时，可以配置负载均衡：

# 配置多个OpenAI渠道
渠道1: OpenAI官方1 (权重: 50)
渠道2: OpenAI官方2 (权重: 30)  
渠道3: OpenAI备用 (权重: 20)

这样配置后：

  • 请求会按权重分配到不同渠道
  • 如果某个渠道失败，自动切换到其他渠道
  • 提高系统的可用性和稳定性

7.2 速率限制和配额管理

OneAPI支持细粒度的访问控制：

  1. 令牌管理：为每个用户或应用创建独立的访问令牌
  2. 速率限制：设置每分钟/每小时的最大请求数
  3. 配额管理：设置每个令牌的总额度（按Token或金额）
  4. IP白名单：限制只有特定IP可以访问

这些功能对于商业应用或SaaS服务特别重要。

7.3 监控和告警

OneAPI提供了完整的监控功能：

  • 实时统计：查看每个渠道的使用情况、成功率、响应时间
  • 额度监控：监控每个用户的剩余额度
  • 失败告警：当渠道连续失败时发送告警
  • 审计日志：记录所有API调用，便于排查问题

你可以配合Message Pusher将告警信息推送到微信、钉钉、飞书等平台。

7.4 自定义和扩展

OneAPI支持丰富的自定义：

  1. 界面自定义：

    • 修改系统名称和Logo
    • 自定义首页和关于页面
    • 支持HTML和Markdown

  2. 功能扩展：

    • 通过管理API扩展功能
    • 支持Webhook通知
    • 可以集成到现有系统中

8. 常见问题解答

8.1 部署相关问题

Q：部署后无法访问Swagger UI？ A：检查以下几点：

  1. 防火墙是否开放了3000端口
  2. Docker容器是否正常运行：docker ps | grep one-api
  3. 查看容器日志：docker logs one-api

Q：如何修改默认端口？ A：在docker-compose.yml中修改端口映射：

ports:
  - "8080:3000"  # 将外部8080端口映射到内部3000端口

8.2 配置相关问题

Q：添加渠道后测试失败？ A：按以下步骤排查：

  1. 检查API Key是否正确
  2. 检查网络是否能访问对应API服务
  3. 查看OneAPI日志中的错误信息
  4. 尝试在渠道设置中启用代理

Q：如何查看API调用日志？ A：在OneAPI管理后台：

  1. 点击"日志"菜单
  2. 可以按时间、用户、渠道等条件筛选
  3. 查看详细的请求和响应信息

8.3 使用相关问题

Q：Swagger UI中测试需要认证，怎么设置？ A：在Swagger UI页面：

  1. 点击右上角的"Authorize"按钮
  2. 输入你的Bearer Token（在OneAPI的"令牌"页面创建）
  3. 点击"Authorize"保存

Q：如何为团队不同成员设置不同权限？ A：OneAPI支持用户角色管理：

  • 管理员：可以管理所有功能
  • 普通用户：只能使用API，不能修改配置
  • 通过用户分组实现更细粒度的权限控制

8.4 性能优化建议

Q：如何提高API响应速度？ A：几个优化建议：

  1. 启用Redis缓存（OneAPI默认已配置）
  2. 配置多个渠道实现负载均衡
  3. 根据业务需求调整超时时间
  4. 对于高频接口，考虑本地缓存结果

Q：如何监控系统性能？ A：OneAPI提供了Prometheus metrics接口：

  • 访问 /metrics 获取监控数据
  • 可以集成到Grafana等监控平台
  • 监控关键指标：请求数、成功率、响应时间、错误率

9. 总结

通过这篇教程，你应该已经掌握了OneAPI的核心功能和使用方法。让我们回顾一下关键点：

OneAPI的核心价值：

  1. 统一接口：用OpenAI格式调用所有主流大模型
  2. 简化管理：一个平台管理所有API Key和渠道
  3. 降低成本：智能路由和负载均衡优化使用成本
  4. 提升效率：自动文档生成和Swagger UI集成

部署和使用流程：

  1. 用Docker一键部署OneAPI服务
  2. 配置你需要的大模型渠道
  3. 使用统一的OpenAI格式调用API
  4. 通过Swagger UI查看文档和测试接口

给团队带来的好处：

  • 新同事快速上手：有完整的API文档和测试工具
  • 前后端高效协作：接口规范明确，减少沟通成本
  • 系统稳定可靠：负载均衡和故障转移保证可用性
  • 成本可控可查：详细的用量统计和配额管理

OneAPI不仅仅是一个API网关，它更是一个完整的大模型API管理解决方案。无论你是个人开发者、创业团队，还是大型企业，都能从中受益。

现在就去部署一个OneAPI实例，体验统一API管理和自动文档生成的便利吧。你会发现，管理多个大模型API，原来可以这么简单。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

Logo
openvela

openvela 操作系统专为 AIoT 领域量身定制，以轻量化、标准兼容、安全性和高度可扩展性为核心特点。openvela 以其卓越的技术优势，已成为众多物联网设备和 AI 硬件的技术首选，涵盖了智能手表、运动手环、智能音箱、耳机、智能家居设备以及机器人等多个领域。

更多推荐

小米开源大模型 MiMo 登顶全球第一，还白送百万亿 Token？手把手教你薅羊毛

小米开源大模型 MiMo 登顶全球第一，还白送百万亿 Token？手把手教你薅羊毛 小米这次不是「年轻人的第一台SUV」，而是「开发者的第一个免费AI大脑」。 📌 导读 ：小米突然开源了自家最强AI大模型 MiMo V2.5，登顶全球开源第一，MIT协议随便商用。更狠的是，同步上线百万亿Token免费送活动，最高价值659元。活动5月28日截止，手慢无。 一、小米突然放大招 4月28日，雷军亲自

avatar openvela
cover

小米开源声音克隆大模型 OmniVoice 完整使用指南｜3 秒克隆人声｜支持 600 多种语言和中文方言｜Apache-2.0 免费商用｜整合包一键启动无需配环境｜附详细安装

avatar openvela
cover

声音克隆 小米大模型 OmniVoice 完整使用指南｜3 秒克隆人声｜支持 600 多种语言和中文方言详细安装教程

avatar openvela