Importing OpenAPI Specs into Xolo

Instead of manually creating requests one by one, Xolo can generate a complete, ready-to-use collection directly from an OpenAPI specification. Every path–method pair in the spec becomes a saved request with its URL, query parameters, headers, and a pre-populated request body generated from the schema — letting you go from spec to first API call in seconds.

Supported Formats

Xolo’s OpenApiService accepts OpenAPI v3 JSON (the openapi key) and Swagger 2.0 JSON (the swagger key). The spec must be a valid JSON object containing:

info.title — becomes the root collection name (falls back to "Imported Collection" if absent)
paths — the map of endpoint definitions

{
  "openapi": "3.0.3",
  "info": { "title": "Pet Store", "version": "1.0.0" },
  "paths": {
    "/pets": { "get": {...}, "post": {...} }
  }
}

ImportManager.detectFormat() identifies an OpenAPI file automatically by looking for an openapi or swagger top-level key, so the format picker can stay on Auto-detect.

Import from URL

Open the Import dialog

Tap the sidebar menu → Import → Collection. The ImportCollectionDialog opens. Ensure the source toggle is set to URL and the format is set to Auto-detect or OpenAPI.

Enter the spec URL

Type or paste the full URL of the OpenAPI JSON spec, for example:

https://api.example.com/openapi.json

Xolo uses Dio to fetch the spec over HTTP/HTTPS.

Xolo fetches and parses the spec

OpenApiService.importFromUrl() issues a GET request to the URL, validates that the response is a Map<String, dynamic>, then calls importFromJson() internally to build the collection tree.

A collection is created

Xolo creates a root collection named after info.title. Requests are grouped into sub-collections by tag. Every path–method combination becomes a saved request under its tag folder. The sidebar refreshes automatically.

Import from File

Switch to File source

In the ImportCollectionDialog, switch the source toggle to File.

Select the spec file

Tap Select file. The file picker opens filtered to .json, .yaml, and .yml extensions. Select your local OpenAPI JSON file.

Import

Tap Import Now. Xolo reads the file bytes, decodes them as UTF-8, calls ImportManager.importFromContent(), and the resulting collection appears in the sidebar.

Generated Request Structure

OpenApiService._parseAndSave() iterates over every paths entry and every HTTP method within it. The logic skips the pseudo-keys parameters, summary, and description so only real method entries produce requests.

Request field	Source in spec	Notes
Name	`operation.summary` → `operation.operationId` → `"{METHOD} {path}"`	First non-null wins
Method	Path method key (e.g. `get`, `post`)	Upper-cased
URL	`servers[0].url` + path	Swagger 2.0: `{scheme}://{host}{basePath}`
Path params	`{param}` syntax in path	Replaced with `{{param}}` Xolo variable syntax
Query params	`parameters[].in == "query"`	Imported as empty active key-value pairs
Headers	`parameters[].in == "header"`	Imported as empty active key-value pairs
Body	`requestBody.content["application/json"].schema`	Sample generated by `SchemaHelper`
Sub-collection	`operation.tags[0]`	First tag becomes the folder name

Tag-based grouping

Endpoints that share the same first tag are placed in the same sub-collection folder. Xolo upserts tag folders — if a folder with the same name already exists under the root collection, it is reused rather than duplicated.

// Simplified excerpt from OpenApiService._parseAndSave()
final tags = operation['tags'] as List<dynamic>?;
if (tags != null && tags.isNotEmpty) {
  final tagName = tags[0] as String;
  collectionId = tagFolders[tagName] ?? await db.createCollection(
    name: tagName,
    parentId: rootId,
  );
  tagFolders[tagName] = collectionId;
}

`OpenApiService` Reference

`importFromUrl`

Future<void> importFromUrl(
  String url,        // Fully-qualified URL to a JSON OpenAPI spec
  int? parentId,     // Parent collection ID, or null for workspace root
  AppDatabase db, {
  int? targetCollectionId,  // Import items into this existing collection
}) async

`importFromJson`

Future<void> importFromJson(
  Map<String, dynamic> json,  // Pre-parsed OpenAPI spec object
  int? parentId,
  AppDatabase db, {
  int? targetCollectionId,
}) async

Both methods share the same internal _parseAndSave() pipeline. importFromUrl adds an HTTP GET fetch step before calling importFromJson.

SchemaHelper — Pre-populated Request Bodies

The import pipeline uses SchemaHelper to turn schema objects into concrete sample payloads. Before writing the request, OpenApiService calls:

SchemaHelper.resolveSchema(schema, rootSpec) — walks $ref pointers within the spec JSON to return a self-contained schema object.
SchemaHelper.generateSample(resolvedSchema) — produces a sample value following this priority: example field → default field → nullable null → enum first value → recursive object/array generation from properties/items. The sample is pretty-printed with a 2-space indent and stored as the request body.

final resolvedSchema = SchemaHelper.resolveSchema(schema, json);
final sample = SchemaHelper.generateSample(resolvedSchema);
if (sample != null) {
  body = const JsonEncoder.withIndent('  ').convert(sample);
}

This also applies to Swagger 2.0 specs where the body is defined as a parameters[].in == "body" entry rather than a requestBody block.

After import, create an environment with a baseUrl variable set to your server’s base address, then reference it in requests as {{baseUrl}}. You can also import the spec directly into an existing collection that already has a {{baseUrl}}-aware environment — subsequent requests inherit it automatically.

Authentication schemes defined in the OpenAPI spec’s securitySchemes or security blocks are not automatically imported. Configure authentication manually on the collection or individual requests using Xolo’s Auth tab after the import completes.

Get Started

Core Features

Authentication

Scripting & Automation

Import & Sync

Importing OpenAPI Specs into Xolo

Supported Formats

Import from URL

Import from File

Generated Request Structure

Tag-based grouping

`OpenApiService` Reference

`importFromUrl`

`importFromJson`

SchemaHelper — Pre-populated Request Bodies

​Supported Formats

​Import from URL

​Import from File

​Generated Request Structure

​Tag-based grouping

​OpenApiService Reference

​importFromUrl

​importFromJson

​SchemaHelper — Pre-populated Request Bodies

Supported Formats

Import from URL

Import from File

Generated Request Structure

Tag-based grouping

`OpenApiService` Reference

`importFromUrl`

`importFromJson`

SchemaHelper — Pre-populated Request Bodies