Importing an OpenAPI API

An OpenAPI spec describes your API; Voozeo derives one tool per operation from it. This page explains how to import it and keep it up to date.

Accepted formats

• Versions: OpenAPI 3.0.x and 3.1.x. Swagger 2.0 is rejected (UNSUPPORTED_SPEC_VERSION): convert it to OpenAPI 3 first.
• Formats: JSON or YAML, files ending in .json, .yaml or .yml.
• Size: 5 MB maximum, whether it is a file or a URL.

Import a file

1. Open the server's "Sources" tab and click "Import an OpenAPI spec".
2. Choose the "File" method and select your file.
3. Click "Import".

A message shows the number of generated tools, with a "View tools" link.

Import from a URL

Choose the "URL" method and enter the public HTTPS address of the spec. Voozeo downloads it: the download is limited to 10 seconds, and a non-2xx response gives UPSTREAM_FETCH_FAILED. Private or internal addresses are refused (UNSAFE_URL). If your spec is not public, import it as a file instead.

The whole import must finish within 28 seconds, otherwise it fails with INGESTION_TIMEOUT.

References ($ref)

Only local references (#/components/schemas/Order) are followed. Voozeo replaces them with their content, with these safeguards:

• nesting deeper than 10 levels is replaced by an empty schema;
• a circular reference is replaced by an empty schema;
• a reference to an external file or URL is ignored (empty schema).

Each of these cases produces a warning (see Warnings).

One source per server

A server holds a single OpenAPI spec. A new import replaces the previous one: that is how updates work.

Update the spec

Simply import the new version. Your customizations (enabled state, name, tool description) are kept for operations that still exist: Voozeo recognizes them by their operationId or, failing that, by method and path. Renaming an operationId in the spec therefore creates a new tool. A base URL you entered yourself in the "Target API" tab is never overwritten. Otherwise the base URL is the first servers entry of the spec (variables replaced by their default value); it must be HTTPS, otherwise it is ignored.

Warnings

A successful import may come with warnings, shown in the "Sources" tab (20 at most, then "And N more."):

Limits

• At most 1,000 operations per spec (beyond that: INVALID_SPEC).
• The request body is only exposed when it is JSON.
• A spec whose expanded content is excessive is refused (INVALID_SPEC, "compiled configuration too large").

Common errors

• UNSUPPORTED_SPEC_VERSION: the file is not OpenAPI 3.0 or 3.1.
• INVALID_SPEC: neither valid JSON nor YAML, missing paths, no operations, or too many operations.
• FILE_TOO_LARGE: more than 5 MB.
• UNSAFE_URL and UPSTREAM_FETCH_FAILED: the URL is forbidden or does not answer properly.
• INGESTION_TIMEOUT: the import took more than 28 seconds.

Example

Here is a minimal spec that produces two tools, listProducts and getOrder:

openapi: 3.0.3
info:
  title: Shop
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /products:
    get:
      operationId: listProducts
      summary: List the products
      parameters:
        - name: inStock
          in: query
          schema: { type: boolean }
      responses:
        "200": { description: OK }
  /orders/{id}:
    get:
      operationId: getOrder
      summary: Read an order by its identifier
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }

After the import, the base URL https://api.example.com is picked up in the "Target API" tab.