Skip to main content

Importing from an OpenAPI Spec

Instead of building a custom activity form from scratch, you can import an OpenAPI (Swagger) specification and let Koodisi automatically generate a full set of activities — one per API endpoint — complete with configuration forms, input/output schemas, and AI-assisted field suggestions.

This is the fastest way to integrate any REST API that publishes an OpenAPI 3.0 document.

What Gets Generated​

For every endpoint in your OpenAPI spec, Koodisi creates:

Generated ItemDescription
Activity nameAI-suggested, based on the endpoint's operation ID and description.
DescriptionAI-generated summary of what the endpoint does.
Tags / GroupAI-suggested activity group derived from the endpoint's tags.
Configuration formFields for path parameters, query parameters, headers, and request body properties.
Input schemaJSON Schema inferred from the request body and parameter definitions.
Output schemaJSON Schema inferred from the response body definitions.
Mappable fieldsAI-suggested fields that are good candidates for Mappable Field binding (e.g., auth headers, IDs, dynamic values).

How to Import​

Step 1 — Access the OpenAPI Import​

Inside the Activity Form Builder, click the Import from OpenAPI button in the toolbar (or follow the prompts in the new activity wizard if starting from scratch).

Step 2 — Provide the Spec URL​

Enter the URL of your OpenAPI document (must be a publicly accessible or network-reachable JSON/YAML endpoint, e.g. https://api.example.com/openapi.json).

Click Fetch — Koodisi loads and parses the spec. A list of all discovered endpoints appears.

Step 3 — Select Endpoints​

Review the list of discovered endpoints. Each row shows:

  • HTTP method (GET, POST, PUT, etc.)
  • Path (e.g., /users/{id})
  • Operation summary (from the spec)

Check the endpoints you want to generate activities for. You can select all or a subset.

Step 4 — AI Metadata Generation​

For each selected endpoint, Koodisi calls an AI model to generate:

  • A human-readable activity name (e.g., "Get User by ID")
  • A concise description of what the activity does
  • A suggested activity group (e.g., "User Management")

This step runs automatically. You can review and edit any generated metadata before proceeding.

Step 5 — Review and Configure​

Each generated activity is shown with its:

  • Auto-generated form fields (mapped from spec parameters and request body)
  • Input/output schema previews
  • Suggested mappable fields highlighted

You can edit any activity's form before saving — add fields, change field types, adjust the layout, or override the AI suggestions.

Step 6 — Save​

Click Save All to create all selected activities in your bundle application. Each activity becomes available in the activity palette across your organization.

How Fields Are Mapped from the Spec​

The import process reads three parts of each OpenAPI operation and turns them into form fields:

OpenAPI SourceGenerated Field TypeNotes
parameters (path)mappableFieldPath params like {userId} become mappable fields bound to the path.
parameters (query)mappableFieldQuery params become mappable fields bound to queryParams/<name>.
parameters (header)mappableFieldHeader params (e.g., X-API-Key) become mappable fields bound to header/<name>.
requestBody propertiestext / number / select / mappableFieldBody properties are converted based on their JSON Schema type.
requestBody enum valuesselectEnum fields become dropdowns with the spec values as options.

Fields that the AI identifies as dynamic (e.g., IDs, auth tokens, tenant-specific values) are automatically configured as Mappable Fields with allowGlobalVariable: true so users can bind them to workflow variables.

Preference Engine​

After the OpenAPI spec is parsed and before the form is rendered, a Preference Engine applies a set of transformation rules to the generated fields. These rules fine-tune the output based on the operation type, parameter location, and field name patterns.

For example:

  • Common authentication headers (Authorization, X-Api-Key) are automatically set as mappable with allowResource: true.
  • Boolean flags are converted to SwitchSelector fields.
  • Fields with a small fixed set of values are converted to select dropdowns.

The Preference Engine runs silently — you see the final result in the review step and can override any field configuration.

Input and Output Schemas​

Each generated activity has:

  • Input schema — a JSON Schema describing the data the activity expects (derived from request parameters and body).
  • Output schema — a JSON Schema describing the data the activity produces (derived from the response body).

These schemas are used by the Mapper activity and the Input/Output Mapping tabs when wiring activities together in a workflow.

Tips​

  • OpenID Connect / OAuth APIs — If the spec defines a securityScheme, Koodisi will flag the relevant header/token fields as mappable so they can be bound to a Managed Resource at deploy time.
  • Large specs — For specs with many endpoints, use the endpoint selector in Step 3 to import in batches.
  • Editing after import — Generated activities can be edited at any time through the normal custom activity flow.
  • Re-importing — Re-running the import for the same spec will create new activities. It does not update existing ones.