操作指南
icon
腾讯元器介绍
搭建智能体应用
对话效果调优技巧
智能体应用发布
智能体应用的体验和分享
知识库管理
开发工作流
插件广场
多智能体应用协作技巧
实践案例合集
从旧版元器迁移智能体到新版元器

OpenAPI、Swagger、Postman 协议的使用说明

更新于 2025-12-29

OpenAPI

OpenAPI 是一种开放的规范，用于描述和定义 RESTful API 的接口。它允许开发者以标准化的方式描述 API 的请求、响应、参数、认证等信息。

填写说明

文件格式：支持 YAML 格式和 JSON 格式。
关键字段说明：
字段
说明
是否必需
openapi
规范版本号，如3.0.0
是
servers
定义 API 的基础 URL 列表
否，但建议填写以生成有效 URL
info
API 元数据，包括标题、版本、描述等
是
paths
定义所有端点（如 /users）及其 HTTP 方法（GET/POST）
是
components
存储可复用的模型、参数、响应等，如 schemas 定义数据结构
否
示例
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: 示例 OpenAPI 文档，包含基础服务器配置

servers:
  - url: "https://example.com/api"
    description: "生产环境 API 服务器"
  - url: "https://sandbox.example.com/api"
    description: "测试环境 API 服务器"

paths:
  /users:
    # GET 请求示例
    get:
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    
    # POST 请求示例
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: 用户创建成功

components:
  schemas:
    User:
      type: object
      required:
        - name
      properties:
        id:
          type: integer
          readOnly: true
          example: 1
        name:
          type: string
          example: "张三"
        email:
          type: string
          format: email
          example: "user@example.com"

Swagger

Swagger 是 OpenAPI 规范的前身和实现工具（Swagger 2.0 是旧版规范），用于描述、文档化和测试 RESTful API，使用与 OpenAPI 相同的文件格式。

填写说明

文件格式：支持 YAML 格式和 JSON 格式。
关键字段说明：
字段
说明
是否必需
swagger
规范版本号，如2.0
是
host
域名
否，但建议填写以生成有效 URL
basePath
基础路径
否，但建议填写以生成有效 URL
schemes
支持的协议，如 http 或 https
否，但建议填写以生成有效 URL
info
API 元数据，包括标题、版本、描述等
是
paths
定义所有端点（如 /users）及其 HTTP 方法（GET/POST）
是
definition
数据模型，相当于 OpenAPI 的 components/schemas
否
示例
swagger: "2.0"

info:
  title: User API
  version: 1.0.0
  description: 示例 Swagger 2.0 文档

host: "example.com"
basePath: "/api"

schemes:
  - "https"

paths:
  /users:
    # GET 请求
    get:
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

    # POST 请求
    post:
      summary: 创建新用户
      parameters:
        - in: body
          name: user
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        '201':
          description: 用户创建成功

definitions:
  User:
    type: object
    required:
      - name
    properties:
      id:
        type: integer
        readOnly: true
        example: 1
      name:
        type: string
        example: "张三"
      email:
        type: string
        format: email
        example: "user@example.com"

主要优化点：
1. 统一了缩进（使用 2 个空格）
2. 在主要部分之间添加了空行分隔
3. 保持注释与相关内容的紧密关联
4. 保持 YAML 的自然层次结构
5. 确保所有列表项和嵌套对象都有正确的缩进

Postman

Postman 是一个 API 开发和测试工具，其 Collection 格式用于保存请求、测试脚本和环境变量，适合手动测试和团队协作。

填写说明

文件格式：支持 JSON 格式。
关键字段说明：
字段
说明
是否必需
info
集合元数据，包括集合名称和集合版本
是
item
请求列表，每个请求需指定方法和 URL
是
request
请求详情，包括 header, body, auth 等
是
auth
认证配置，如 API Key
否
event
预请求脚本或测试脚本
否
示例
{
  "info": {
    "name": "User API Collection",
    "version": "1.0.0",
    "description": "示例 Postman 集合，包含 GET 和 POST 请求"
  },
  "item": [
    {
      "name": "用户管理",
      "item": [
        {
          "name": "获取所有用户 (GET)",
          "request": {
            "method": "GET",
            "url": "https://api.example.com/users",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ]
          },
          "response": []
        },
        {
          "name": "创建用户 (POST)",
          "request": {
            "method": "POST",
            "url": "https://api.example.com/users",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}"
            }
          },
          "response": []
        }
      ]
    }
  ]
}