Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JonathanHerSa/xolo-api-hub/llms.txt

Use this file to discover all available pages before exploring further.

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

1

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.
2

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.
3

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.
4

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

1

Switch to File source

In the ImportCollectionDialog, switch the source toggle to File.
2

Select the spec file

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

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 fieldSource in specNotes
Nameoperation.summary → operation.operationId → "{METHOD} {path}"First non-null wins
MethodPath method key (e.g. get, post)Upper-cased
URLservers[0].url + pathSwagger 2.0: {scheme}://{host}{basePath}
Path params{param} syntax in pathReplaced with {{param}} Xolo variable syntax
Query paramsparameters[].in == "query"Imported as empty active key-value pairs
Headersparameters[].in == "header"Imported as empty active key-value pairs
BodyrequestBody.content["application/json"].schemaSample generated by SchemaHelper
Sub-collectionoperation.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:
  1. SchemaHelper.resolveSchema(schema, rootSpec) — walks $ref pointers within the spec JSON to return a self-contained schema object.
  2. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us