Skip to main content

OpenAPI/Swagger Support

GeniSpace supports importing operators from OpenAPI and Swagger documents. This document provides detailed information about supported versions and formats.

Supported Versions​

OpenAPI Specification​

  • OpenAPI 3.x: Supports the OpenAPI 3.x series
    • Supports standard features: paths, components, servers, security, etc.
    • Automatically detects the openapi field to identify OpenAPI 3.x documents

Swagger Specification​

  • Swagger 2.0: Supports the Swagger 2.0 specification
    • Also known as OpenAPI 2.0
    • Supports standard features: paths, definitions, parameters, responses, etc.
    • Automatically detects the swagger field to identify Swagger 2.0 documents
note

The system determines the document type by detecting the openapi or swagger field in the document. The specific version compatibility depends on the standardization level of the document structure.

Supported File Formats​

JSON Format​

{
  "openapi": "3.0.3",
  "info": {
    "title": "Example API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get user list",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

YAML Format​

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get user list
      responses:
        '200':
          description: Success

Version Detection Mechanism​

The system automatically detects the document type:

  1. OpenAPI 3.x Detection: Looks for the openapi field

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

  2. Swagger 2.0 Detection: Looks for the swagger field

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

  3. Format Detection:

    • JSON: File starts with { or Content-Type contains json
    • YAML: All other cases default to YAML parsing

  4. Basic Validation:

    • Checks for the required paths field
    • Validates the basic completeness of the document structure

Import Features​

Multi-Method Import​

  • Import multiple API endpoints from a single OpenAPI document
  • Each endpoint is automatically converted into a method of the operator
  • Supports batch selection of methods to import

Automatic Parsing​

  • Server URL: Automatically extracted from the servers field
  • Request Parameters: Input Schema generated from requestBody and parameters
  • Response Structure: Output Schema generated from responses
  • Scope of Import: Only endpoint paths and request/response schemas are imported. Authentication is not read from the document — you must configure it manually after import (see the FAQ below)

Schema Conversion​

  • OpenAPI Schema → GeniSpace Schema
  • Data types and validation rules are preserved
  • Port identification (isPort) is added
  • Reference ($ref) resolution is handled

Import Methods​

note

Import is processed client-side in the browser: the document is fetched and parsed directly by your browser, not by the GeniSpace backend. As a result, URL import is subject to CORS — internal-network API documentation URLs that do not return CORS headers will often fail to load. In that case, download the document and use File Upload instead.

1. File Upload​

Supported file extensions:

  • .json - JSON format
  • .yaml - YAML format
  • .yml - YAML format

2. URL Import​

Supports importing from the following sources:

  • Public OpenAPI document URLs
  • Internal network API document addresses
  • Supports both HTTP and HTTPS protocols

Example Documents​

Complete OpenAPI 3.0 Example​

openapi: 3.0.3
info:
  title: User Management API
  description: RESTful API for the user management system
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production environment
paths:
  /users:
    get:
      summary: Get user list
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Successfully returned user list
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
    post:
      summary: Create new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Get user details
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successfully returned user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
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 Example​

swagger: '2.0'
info:
  title: User Management API
  description: RESTful API for the user management system
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https
paths:
  /users:
    get:
      summary: Get user list
      parameters:
        - name: page
          in: query
          type: integer
          default: 1
        - name: limit
          in: query
          type: integer
          default: 10
      responses:
        '200':
          description: Successfully returned user list
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  $ref: '#/definitions/User'
              total:
                type: integer
    post:
      summary: Create new user
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          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

FAQ​

Q: Why did my document import fail?​

A: Please check the following:

  1. Does the document contain an openapi or swagger field?
  2. Is the document format valid JSON or YAML?
  3. Does it contain a non-empty paths definition?
  4. Is the network connection working properly (for URL imports)?
  5. Does the document structure conform to the basic OpenAPI/Swagger specification?

Q: How does the system handle different versions of OpenAPI documents?​

A: The system uses a lenient parsing strategy:

  • Any document containing the openapi field is treated as OpenAPI 3.x
  • Any document containing the swagger field is treated as Swagger 2.0
  • Specific version numbers are not strictly validated
  • Focus is on core structures such as paths, components/definitions, etc.

Q: What authentication methods are supported?​

A: The importer does not read or apply authentication from the document — it only imports endpoint paths and request/response schemas. After import, you can manually configure any of the following auth types on the operator:

  • API Key authentication
  • Bearer Token authentication
  • Basic authentication
  • Custom Header authentication

Q: How are complex Schema references handled?​

A: The system will attempt to resolve $ref references, but with limitations:

  • Simple references are processed
  • Complex nested references may be simplified
  • A reference that cannot be resolved becomes an empty object { type: "object", properties: {} }
  • It is recommended to manually adjust the generated Schema after import

Q: Can method configurations be modified after import?​

A: Yes, after import you can:

  • Modify method names and descriptions
  • Adjust input/output Schemas
  • Configure caching and retry policies
  • Add or delete methods

Q: Why were some API endpoints not imported?​

A: Possible reasons:

  • Endpoint definitions are incomplete or incorrectly formatted
  • Required HTTP method definitions are missing
  • Path definitions contain syntax errors
  • It is recommended to check the structural completeness of the original document

Best Practices​

  1. Document Quality: Ensure your OpenAPI document is complete and accurate

    • Include the required openapi or swagger field
    • Ensure paths definitions are not empty
    • Provide clear API descriptions and summaries

  2. Version Management: Use explicit version identifiers

    • Specify the version in info.version
    • Keep the document synchronized with the actual API

  3. Descriptive Information: Provide detailed API descriptions and examples

    • Add summary and description for each endpoint
    • Include field descriptions in Schemas

  4. Error Handling: Define complete error responses

    • Don't only define success responses (200, 201)
    • Also define common error responses (400, 401, 404, 500)

  5. Security Configuration: Properly configure authentication and authorization information

    • Manually configure authentication information after import
    • Use environment variables to manage sensitive information

  6. Schema Design:

    • Avoid overly complex nested references
    • Use clear data type definitions
    • Add required markers for mandatory fields

  7. Testing and Validation:

    • Validate the document format before importing
    • Test the generated method configurations after import
    • Verify that input/output Schemas are correct