跳到主要内容

OpenAPI/Swagger 支持说明

GeniSpace 系统支持从 OpenAPI 和 Swagger 文档导入工具，本文档详细说明支持的版本和格式。

支持的版本​

OpenAPI 规范​

  • OpenAPI 3.x: 支持 OpenAPI 3.x 系列版本
    • 支持标准特性：paths, components, servers, security 等
    • 自动检测 openapi 字段来识别 OpenAPI 3.x 文档

Swagger 规范​

  • Swagger 2.0: 支持 Swagger 2.0 规范
    • 也称为 OpenAPI 2.0
    • 支持标准特性：paths, definitions, parameters, responses 等
    • 自动检测 swagger 字段来识别 Swagger 2.0 文档

注意: 系统通过检测文档中的 openapi 或 swagger 字段来判断文档类型，具体的版本兼容性取决于文档结构的标准化程度。

支持的文件格式​

JSON 格式​

{
  "openapi": "3.0.3",
  "info": {
    "title": "示例 API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "获取用户列表",
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    }
  }
}

YAML 格式​

openapi: 3.0.3
info:
  title: 示例 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功

版本检测机制​

系统会自动检测文档类型：

  1. OpenAPI 3.x 检测：查找 openapi 字段

    {
      "openapi": "3.0.3",
      // ...
    }

  2. Swagger 2.0 检测：查找 swagger 字段

    {
      "swagger": "2.0",
      // ...
    }

  3. 格式检测：

    • JSON：文件以 { 开头或 Content-Type 包含 json
    • YAML：其他情况默认按 YAML 解析

  4. 基本验证：

    • 检查是否包含必需的 paths 字段
    • 验证文档结构的基本完整性

导入功能特性​

多方法导入​

  • 从单个 OpenAPI 文档导入多个 API 端点
  • 每个端点自动转换为工具的一个方法
  • 支持批量选择要导入的方法

自动解析​

  • 服务器地址：从 servers 字段自动提取
  • 请求参数：从 requestBody 和 parameters 生成输入 Schema
  • 响应结构：从 responses 生成输出 Schema
  • 认证信息：从 security 和 securitySchemes 解析

Schema 转换​

  • OpenAPI Schema → GeniSpace Schema
  • 保持数据类型和验证规则
  • 添加端口标识（isPort）
  • 处理引用（$ref）解析

使用方式​

1. 文件上传​

支持的文件扩展名：

  • .json - JSON 格式
  • .yaml - YAML 格式
  • .yml - YAML 格式

2. URL 导入​

支持从以下来源导入：

  • 公开的 OpenAPI 文档 URL
  • 内网 API 文档地址
  • 支持 HTTP 和 HTTPS 协议

3. 手动粘贴​

  • 直接粘贴 OpenAPI 文档内容
  • 支持 JSON 和 YAML 格式
  • 实时验证文档格式

示例文档​

完整的 OpenAPI 3.0 示例​

openapi: 3.0.3
info:
  title: 用户管理 API
  description: 用户管理系统的 RESTful API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: 获取用户详情
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email

Swagger 2.0 示例​

swagger: '2.0'
info:
  title: 用户管理 API
  description: 用户管理系统的 RESTful API
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          type: integer
          default: 1
        - name: limit
          in: query
          type: integer
          default: 10
      responses:
        '200':
          description: 成功返回用户列表
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  $ref: '#/definitions/User'
              total:
                type: integer
    post:
      summary: 创建新用户
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          schema:
            $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      email:
        type: string
        format: email
      created_at:
        type: string
        format: date-time
  CreateUserRequest:
    type: object
    required:
      - name
      - email
    properties:
      name:
        type: string
        minLength: 1
        maxLength: 100
      email:
        type: string
        format: email

常见问题​

Q: 为什么我的文档导入失败？​

A: 请检查：

  1. 文档是否包含 openapi 或 swagger 字段
  2. 文档格式是否为有效的 JSON 或 YAML
  3. 是否包含 paths 定义且不为空
  4. 网络连接是否正常（URL 导入时）
  5. 文档结构是否符合基本的 OpenAPI/Swagger 规范

Q: 系统如何处理不同版本的 OpenAPI 文档？​

A: 系统采用宽松的解析策略：

  • 只要文档包含 openapi 字段就按 OpenAPI 3.x 处理
  • 只要文档包含 swagger 字段就按 Swagger 2.0 处理
  • 不会严格验证具体的版本号
  • 重点关注 paths、components/definitions 等核心结构

Q: 支持哪些认证方式？​

A: 目前支持：

  • API Key 认证
  • Bearer Token 认证
  • Basic 认证
  • 自定义 Header 认证

Q: 如何处理复杂的 Schema 引用？​

A: 系统会尝试解析 $ref 引用，但有限制：

  • 简单的引用会被处理
  • 复杂的嵌套引用可能被简化为空对象
  • 建议导入后手动调整生成的 Schema

Q: 导入后可以修改方法配置吗？​

A: 可以，导入后可以：

  • 修改方法名称和描述
  • 调整输入输出 Schema
  • 配置缓存和重试策略
  • 添加或删除方法

Q: 为什么某些 API 端点没有被导入？​

A: 可能的原因：

  • 端点定义不完整或格式不正确
  • 缺少必要的 HTTP 方法定义
  • 路径定义存在语法错误
  • 建议检查原始文档的结构完整性

最佳实践​

  1. 文档质量：确保 OpenAPI 文档完整且准确

    • 包含必要的 openapi 或 swagger 字段
    • 确保 paths 定义不为空
    • 提供清晰的 API 描述和摘要

  2. 版本管理：使用明确的版本号标识

    • 在 info.version 中指定版本
    • 保持文档与实际 API 的同步

  3. 描述信息：提供详细的 API 描述和示例

    • 为每个端点添加 summary 和 description
    • 在 Schema 中添加字段描述

  4. 错误处理：定义完整的错误响应

    • 不仅定义成功响应（200、201）
    • 也要定义常见的错误响应（400、401、404、500）

  5. 安全配置：正确配置认证和授权信息

    • 在导入后手动配置认证信息
    • 使用环境变量管理敏感信息

  6. Schema 设计：

    • 避免过于复杂的嵌套引用
    • 使用清晰的数据类型定义
    • 为必填字段添加 required 标记

  7. 测试验证：

    • 导入前先验证文档格式
    • 导入后测试生成的方法配置
    • 检查输入输出 Schema 是否正确

相关文档​