OpenAPI Requirements

Helper uses OpenAPI specifications to understand your API's capabilities and convert them into usable tools. To ensure optimal integration, your OpenAPI specification should meet certain requirements.

Supported OpenAPI Versions

Helper supports:

• OpenAPI 3.0.x
• OpenAPI 3.1.x

Earlier versions (such as Swagger 2.0) may work but are not officially supported.

Essential Components

Your OpenAPI specification should include:

1. Clear Operation IDs

Each endpoint should have a unique operationId that clearly describes the action:

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      # ...

Helper uses these operation IDs to name and identify tools.

2. Detailed Descriptions

Include descriptions for:

• Each endpoint
• Parameters
• Request bodies
• Response schemas

paths:
  /orders/{orderId}:
    get:
      operationId: getOrderById
      description: "Retrieves detailed information about a specific order"
      parameters:
        - name: orderId
          in: path
          required: true
          description: "The unique identifier of the order"
          schema:
            type: string

These descriptions help Helper understand when and how to use each tool.

3. Well-Defined Parameters

Clearly define all parameters, including:

• Type information
• Format constraints
• Whether they're required
• Default values (when applicable)

parameters:
  - name: limit
    in: query
    description: "Maximum number of results to return"
    required: false
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20

4. Response Schemas

Define response schemas to help Helper understand the data structure returned by each endpoint:

responses:
  200:
    description: "Successful operation"
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            # ...

Authentication

If your API requires authentication, specify it in the OpenAPI document:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Helper currently supports API key authentication, which can be specified during the API connection process.

Best Practices

For optimal integration with Helper:

Endpoint Organization

• Group related endpoints logically
• Use consistent naming conventions for paths and operations
• Keep the number of endpoints manageable (prioritize the most useful ones)

Parameter Design

• Use descriptive parameter names
• Provide examples where helpful
• Define appropriate constraints (min/max values, patterns, etc.)

Documentation

• Include comprehensive descriptions
• Document potential errors and status codes
• Provide examples of requests and responses

Versioning

• Include version information in your specification
• Maintain backward compatibility when possible
• Document breaking changes clearly

Example Specification

Here's a simplified example of a well-structured OpenAPI specification:

openapi: 3.0.0
info:
  title: E-commerce API
  description: API for managing orders and customers
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderById
      description: Retrieve order details by ID
      parameters:
        - name: orderId
          in: path
          required: true
          description: The unique identifier of the order
          schema:
            type: string
      responses:
        200:
          description: Order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        customer:
          $ref: '#/components/schemas/Customer'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        total:
          type: number
          format: float
    # Additional schema definitions...

Troubleshooting

If Helper has trouble parsing your OpenAPI specification:

• Validate your specification using tools like the Swagger Validator
• Check for missing required fields (operationIds, descriptions, etc.)
• Ensure your specification is accessible from the provided URL
• Verify that the specification follows the OpenAPI standard