feat: add openapi contract import for consumed rest services (closes mendixlabs#207 )

Author: khode-mx

.claude/skills/mendix/rest-client.md

@@ -131,6 +131,49 @@ CREATE OR MODIFY REST CLIENT Module.ClientName ...  -- idempotent
 
 ---
 
+## Importing from OpenAPI
+
+When an OpenAPI 3.0 JSON spec is available, use `IMPORT REST CLIENT` instead of writing
+`CREATE REST CLIENT` by hand. The spec is parsed automatically and stored in the service
+document — exactly as Studio Pro does.
+
+```sql
+-- Import from an OpenAPI 3.0 JSON spec file
+IMPORT REST CLIENT Module.YourAPI FROM OPENAPI '/path/to/openapi.json';
+
+-- Idempotent: replace an existing service with the same name
+IMPORT OR REPLACE REST CLIENT Module.YourAPI FROM OPENAPI '/path/to/openapi.json';
+
+-- Override BaseUrl (use when spec has no servers array)
+IMPORT REST CLIENT Module.YourAPI FROM OPENAPI '/path/to/openapi.json'
+  SET BaseUrl: 'https://api.example.com';
+
+-- Override BaseUrl and Authentication together
+IMPORT OR REPLACE REST CLIENT Module.YourAPI FROM OPENAPI '/path/to/openapi.json'
+  SET BaseUrl: 'https://api.example.com',
+      Authentication: BASIC (Username: '$Module.ApiUser', Password: '$Module.ApiPass');
+
+-- Preview what will be generated (no project connection needed)
+DESCRIBE OPENAPI FILE '/path/to/openapi.json';
+```
+
+**What gets set from the spec:**
+- `BaseUrl` ← `servers[0].url` (trailing slash stripped)
+- One operation per `paths[path][method]` entry
+  - `Name` ← `operationId` (sanitized to valid identifier; fallback: `METHOD_path_slug`)
+  - `Path` ← OpenAPI path (same `{param}` placeholder format as Mendix)
+  - `Parameters` ← `in: path` parameters (type mapped to Mendix types)
+  - `QueryParameters` ← `in: query` parameters
+  - `BodyType: JSON` ← when `requestBody` is present
+  - `ResponseType: JSON` ← when a 200/201 response exists; otherwise `NONE`
+  - `Timeout: 300` ← Mendix default
+  - `Tags` ← OpenAPI tags (stored on operation; informational)
+- `OpenApiFile.Content` ← raw spec JSON (stored as-is, same as Studio Pro)
+
+**Requirements:** Mendix 10.1+.
+
+---
+
 ## Approach 2: REST CALL (Inline HTTP)
 
 Call an HTTP endpoint directly from a microflow — no REST client document needed. Best for one-off calls, dynamic URLs, or low-level control.

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to mxcli will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
+
+- **IMPORT REST CLIENT FROM OPENAPI** — Create a consumed REST service from an OpenAPI 3.0 JSON spec: `IMPORT REST CLIENT Module.Name FROM OPENAPI '/path/spec.json'`
+- **IMPORT OR REPLACE REST CLIENT** — Idempotent variant that replaces an existing service with the same name
+- **DESCRIBE OPENAPI FILE** — Preview an OpenAPI spec as MDL without a project connection: `DESCRIBE OPENAPI FILE '/path/spec.json'`
+- **IMPORT REST CLIENT … SET** — Optional `SET BaseUrl: '...'` and `SET Authentication: BASIC (...)` overrides for specs without servers or securitySchemes
+
+### Fixed
+
+- **DELETE/HEAD body stripping** — Specs with a `requestBody` on DELETE or HEAD operations (e.g. `deleteTask`) now correctly produce `Rest$RestOperationMethodWithoutBody`, matching Studio Pro's behavior
+
 ## [0.6.0] - 2026-04-09
 
 ### Added

cmd/mxcli/docker/detect.go

@@ -13,10 +13,10 @@
 // CDN downloads are the primary source for mxbuild and runtime.
 //
 // Resolution priority (all platforms):
-//   1. Explicit path (--mxbuild-path)
-//   2. PATH lookup
-//   3. OS-specific known locations (Studio Pro on Windows)
-//   4. Cached CDN downloads (~/.mxcli/mxbuild/)
+//  1. Explicit path (--mxbuild-path)
+//  2. PATH lookup
+//  3. OS-specific known locations (Studio Pro on Windows)
+//  4. Cached CDN downloads (~/.mxcli/mxbuild/)
 //
 // Path discovery on Windows must NOT hardcode drive letters. Use environment
 // variables (PROGRAMFILES, PROGRAMW6432, SystemDrive) to locate install dirs.

cmd/mxcli/help_topics/rest.txt

@@ -50,6 +50,21 @@ CREATE REST CLIENT
   CREATE OR MODIFY REST CLIENT Module.Api ( ... ) { ... };  -- Update existing
   DROP REST CLIENT Module.Api;
 
+IMPORT REST CLIENT FROM OPENAPI
+--------------------------------
+
+  -- Import a consumed REST service from an OpenAPI 3.0 JSON spec:
+  IMPORT REST CLIENT Module.YourAPI FROM OPENAPI '/specs/openapi.json';
+
+  -- Idempotent: replace an existing service with the same name:
+  IMPORT OR REPLACE REST CLIENT Module.YourAPI FROM OPENAPI '/specs/openapi.json';
+
+  -- Preview what will be created (no project needed):
+  DESCRIBE OPENAPI FILE '/specs/openapi.json';
+
+  The raw spec is stored in the service document (Rest$OpenApiFile.Content),
+  matching Studio Pro's import behavior. Requires Mendix 10.1+.
+
   Authentication: NONE | BASIC (Username: '...', Password: '...')
   Body: JSON FROM $var | TEMPLATE '...' | MAPPING Entity { jsonField = Attr, ... }
   Response: JSON AS $var | STRING AS $var | FILE AS $var | STATUS AS $var | NONE

cmd/mxcli/lsp_completions_gen.go

@@ -250,6 +250,8 @@
 - [Workflow Statements](reference/workflow/README.md)
   - [CREATE WORKFLOW](reference/workflow/create-workflow.md)
   - [DROP WORKFLOW](reference/workflow/drop-workflow.md)
+- [REST Client Statements](reference/rest-client/README.md)
+  - [IMPORT REST CLIENT FROM OPENAPI](reference/rest-client/import-rest-client.md)
 - [OData and Integration Statements](reference/odata/README.md)
 - [Business Event Statements](reference/business-event/README.md)
   - [CREATE BUSINESS EVENT SERVICE](reference/business-event/create-business-event-service.md)

docs-site/src/SUMMARY.md

@@ -0,0 +1,40 @@
+# REST Client Statements
+
+Statements for creating and managing consumed REST services (REST clients).
+
+A REST client document defines a third-party HTTP API — its base URL, authentication, and operations — once. Microflows then call its operations using `SEND REST REQUEST` without repeating connection details.
+
+## Import from OpenAPI
+
+| Statement | Description |
+|-----------|-------------|
+| [IMPORT REST CLIENT FROM OPENAPI](import-rest-client.md) | Create a consumed REST service from an OpenAPI 3.0 JSON spec |
+| [DESCRIBE OPENAPI FILE](import-rest-client.md#describe-openapi-file) | Preview what an OpenAPI spec would generate — no project needed |
+
+## Create / Modify / Drop
+
+| Statement | Description |
+|-----------|-------------|
+| `CREATE REST CLIENT Module.Name ( ... ) { ... }` | Create a REST client manually |
+| `CREATE OR MODIFY REST CLIENT Module.Name ( ... ) { ... }` | Idempotent create/update |
+| `DROP REST CLIENT Module.Name` | Remove a REST client |
+
+## Show / Describe
+
+| Statement | Description |
+|-----------|-------------|
+| `SHOW REST CLIENTS [IN Module]` | List all consumed REST services |
+| `DESCRIBE REST CLIENT Module.Name` | Show full MDL definition (re-executable) |
+
+## Catalog Tables
+
+After `REFRESH CATALOG`, the following tables are available:
+
+| Table | Contents |
+|-------|----------|
+| `CATALOG.REST_CLIENTS` | Consumed REST services |
+| `CATALOG.REST_OPERATIONS` | Operations per service (method, path, parameters) |
+
+## Requirements
+
+REST client documents require **Mendix 10.1+**.

docs-site/src/reference/rest-client/README.md

@@ -0,0 +1,105 @@
+# IMPORT REST CLIENT FROM OPENAPI
+
+Import a consumed REST service from an OpenAPI 3.0 JSON specification in one step. The spec is parsed automatically and stored in the service document — exactly as Mendix Studio Pro does when you use its built-in OpenAPI import.
+
+**Requires Mendix 10.1+.**
+
+## Syntax
+
+```sql
+IMPORT REST CLIENT Module.Name FROM OPENAPI '/path/to/openapi.json';
+
+-- Idempotent: replace an existing service with the same name
+IMPORT OR REPLACE REST CLIENT Module.Name FROM OPENAPI '/path/to/openapi.json';
+
+-- Override base URL (use when spec has no servers array)
+IMPORT REST CLIENT Module.Name FROM OPENAPI '/path/to/openapi.json'
+  SET BaseUrl: 'https://api.example.com';
+
+-- Override base URL and authentication
+IMPORT OR REPLACE REST CLIENT Module.Name FROM OPENAPI '/path/to/openapi.json'
+  SET BaseUrl: 'https://api.example.com',
+      Authentication: BASIC (Username: '$Module.ApiUser', Password: '$Module.ApiPass');
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `Module.Name` | Qualified name for the new REST client. Module must already exist. |
+| `'/path/to/openapi.json'` | Absolute or relative path to the OpenAPI 3.0 JSON spec file. |
+| `OR REPLACE` | If a REST client with the same name already exists, replace it. Without this clause the command fails if the service already exists. |
+| `SET BaseUrl` | Override the base URL from the spec's `servers[0].url`. Required when the spec has no `servers` array. |
+| `SET Authentication` | Override the authentication. Supported values: `NONE`, `BASIC (Username: '...', Password: '...')`. |
+
+## What Gets Imported
+
+| OpenAPI Field | REST Client Field |
+|---------------|-------------------|
+| `servers[0].url` | `BaseUrl` (trailing slash stripped) |
+| `paths[path][method].operationId` | Operation name (sanitized to valid identifier) |
+| `paths[path]` | `Path` (same `{param}` placeholder format as Mendix) |
+| `paths[path][method]` | `Method` (uppercased: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
+| `parameters[*].in = "path"` | `Parameters` |
+| `parameters[*].in = "query"` | `Query` |
+| `requestBody` (non-DELETE/HEAD) | `Body: JSON` |
+| `responses["200"/"201"/"2XX"]` | `Response: JSON` |
+| `responses["204"]` / no 2xx | `Response: NONE` |
+| Raw spec bytes | `OpenApiFile.Content` (stored as-is, enables "View OpenAPI" in Studio Pro) |
+
+**Note:** duplicate parameter names within a single operation (a spec authoring error) are preserved as-is, matching Studio Pro behaviour. Studio Pro will surface these as warnings when you open the project.
+
+### Type Mapping
+
+| OpenAPI Type | Format | Mendix Type |
+|--------------|--------|-------------|
+| `string` | — | `String` |
+| `integer` | `int32` (or none) | `Integer` |
+| `integer` | `int64` | `Long` |
+| `number` | — | `Decimal` |
+| `boolean` | — | `Boolean` |
+
+## Examples
+
+### Basic import
+
+```sql
+-- Create the module first
+CREATE MODULE PetStoreIntegration;
+
+-- Import all endpoints from the spec
+IMPORT REST CLIENT PetStoreIntegration.PetStoreAPI FROM OPENAPI '/specs/petstore.json';
+```
+
+### Spec without servers array
+
+```sql
+IMPORT REST CLIENT MyModule.YourAPI FROM OPENAPI '/specs/openapi.json'
+  SET BaseUrl: 'https://api.example.com/v1';
+```
+
+### Idempotent re-import after spec update
+
+```sql
+IMPORT OR REPLACE REST CLIENT MyModule.YourAPI FROM OPENAPI '/specs/openapi.json';
+```
+
+## DESCRIBE OPENAPI FILE
+
+Preview what `IMPORT REST CLIENT` would generate without modifying the project. No project connection is needed.
+
+```sql
+DESCRIBE OPENAPI FILE '/path/to/openapi.json';
+```
+
+Output is a complete `CREATE REST CLIENT` statement — re-executable MDL showing all operations that would be created.
+
+## Studio Pro Compatibility
+
+The raw spec is stored in the service document's `OpenApiFile.Content` field. When you open the project in Studio Pro, the REST client shows a **View OpenAPI** button and validates operations against the spec, exactly as if you had used Studio Pro's built-in import.
+
+## Related
+
+- [REST Client Statements](README.md) — overview of all REST client commands
+- [SEND REST REQUEST](../../language/microflow/send-rest-request.md) — call an operation from a microflow
+- `SHOW REST CLIENTS` / `DESCRIBE REST CLIENT Module.Name` — list and inspect imported services

docs-site/src/reference/rest-client/import-rest-client.md

@@ -448,6 +448,9 @@ CREATE OR REPLACE NAVIGATION Responsive
 | Create client | See syntax below | Property-based `{}` syntax |
 | Create or modify | `CREATE OR MODIFY REST CLIENT ...` | Replaces existing |
 | Drop client | `DROP REST CLIENT Module.Name;` | |
+| Import from OpenAPI | `IMPORT REST CLIENT Module.Name FROM OPENAPI '/path/spec.json';` | Creates service from OpenAPI 3.0 JSON spec; requires 10.1+ |
+| Import or replace | `IMPORT OR REPLACE REST CLIENT Module.Name FROM OPENAPI '/path/spec.json';` | Idempotent — replaces existing service |
+| Preview OpenAPI spec | `DESCRIBE OPENAPI FILE '/path/spec.json';` | No project needed; outputs CREATE preview |
 
 ```sql
 CREATE REST CLIENT Module.Api (