feat: import consumed REST client from OpenAPI 3.0 spec (closes #207)

Add `OpenAPI: 'path/or/url'` property to `CREATE REST CLIENT` that
auto-generates a consumed REST service document from an OpenAPI 3.0
spec (JSON or YAML). Operations, path/query parameters, request bodies,
response types, resource groups (tags), and Basic auth are all derived
from the spec. The spec content is stored in OpenApiFile for Studio Pro
parity. Also adds `DESCRIBE CONTRACT OPERATION FROM OPENAPI` for
previewing the import without writing to the project.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: khode-mx

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

@@ -2,20 +2,52 @@
 
 Use this skill when integrating with external REST APIs from Mendix.
 
-## Two Approaches
+## Three Approaches
 
-Mendix offers two ways to call REST APIs from microflows. Choose based on the use case:
+Mendix offers three ways to call REST APIs from microflows. Choose based on the use case:
 
 | Approach | When to Use | Artifacts |
 |----------|-------------|-----------|
-| **REST Client + SEND REST REQUEST** | Structured APIs with multiple operations, reusable across microflows, Studio Pro UI support | REST client document + microflow |
+| **OpenAPI import** | API has an OpenAPI 3.0 spec — auto-generate from the spec | REST client document generated in one command |
+| **REST Client (manual)** | No spec available, or need fine-grained control | REST client document + microflow |
 | **REST CALL (inline)** | One-off calls, quick prototyping, dynamic URLs, low-level HTTP control | Microflow only |
 
-Both can be combined with **Data Transformers** (Mendix 11.9+) and **Import/Export Mappings** to map between JSON and entities.
+Both REST Client approaches can be combined with **Data Transformers** (Mendix 11.9+) and **Import/Export Mappings** to map between JSON and entities.
 
 ---
 
-## Approach 1: REST Client (Recommended)
+## Approach 0: OpenAPI Import (Fastest)
+
+If the API has an OpenAPI 3.0 spec (JSON or YAML), generate the REST client in one command:
+
+```sql
+-- From a local file (relative to the .mpr file)
+create or modify rest client CapitalModule.CapitalAPI (
+  OpenAPI: 'specs/capital.json'
+);
+
+-- From a URL
+create or modify rest client PetStoreModule.PetStoreAPI (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
+);
+```
+
+This generates:
+- All operations with correct HTTP method, path, parameters, headers, body, and response type
+- Resource groups based on OpenAPI `tags`
+- Basic auth if the spec declares it at the top level
+- The spec stored inside the document for Studio Pro parity
+
+**Preview without writing:**
+```sql
+describe contract operation from openapi 'specs/capital.json';
+```
+
+**After import:** the REST client is ready to use with `SEND REST REQUEST`. No manual operation definition needed.
+
+---
+
+## Approach 1: REST Client (Manual)
 
 Define the API once as a REST client document, then call its operations from microflows.
 

CHANGELOG.md

@@ -13,6 +13,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Path normalization** — Relative paths in `MetadataUrl` are automatically converted to absolute `file://` URLs for Studio Pro compatibility
 - **ServiceUrl validation** — `ServiceUrl` parameter must now be a constant reference (e.g., `@Module.ConstantName`) to enforce Mendix best practice
 - **Shared URL utilities** — `internal/pathutil` package with `NormalizeURL()`, `URIToPath()`, and `PathFromURL()` for reuse across components
+- **OpenAPI import for REST clients** — `CREATE REST CLIENT` now accepts `OpenAPI: 'path/or/url'` to auto-generate a consumed REST service document from an OpenAPI 3.0 spec (JSON or YAML); operations, path/query parameters, request bodies, response types, resource groups (tags), and Basic auth are derived automatically; spec content is stored in `OpenApiFile` for Studio Pro parity (#207)
+- **DESCRIBE CONTRACT OPERATION FROM OPENAPI** — Preview what would be generated from an OpenAPI spec without writing to the project
+
 ## [0.7.0] - 2026-04-21
 
 ### Added

cmd/mxcli/lsp_completions_gen.go

@@ -182,6 +182,31 @@ CREATE IMPORT MAPPING Integration.IMM_Order
 
 ## Consuming a REST API
 
+### From an OpenAPI Spec (Recommended)
+
+If the API has an OpenAPI 3.0 spec (JSON or YAML), generate the REST client in one command:
+
+```sql
+-- From a local file (relative to the .mpr file)
+CREATE OR MODIFY REST CLIENT CapitalModule.CapitalAPI (
+  OpenAPI: 'specs/capital.json'
+);
+
+-- From a URL
+CREATE OR MODIFY REST CLIENT PetStoreModule.PetStoreAPI (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
+);
+```
+
+Operations, path/query parameters, request bodies, response types, resource groups (from `tags`), and Basic auth are all derived automatically from the spec.
+
+**Preview without writing:**
+```sql
+DESCRIBE CONTRACT OPERATION FROM OPENAPI 'specs/capital.json';
+```
+
+### Manual Definition
+
 Define a reusable REST client with typed operations using `CREATE REST CLIENT`. Each operation declares its method, path, optional parameters, headers, body, and response mapping.
 
 ```sql

cmd/mxcli/syntax/features_integration.go

@@ -84,6 +84,7 @@ Everything mxcli can do, organized by use case.
 | Capability | Command | Status |
 |---|---|---|
 | REST clients | `CREATE REST CLIENT` | Consumed REST services |
+| OpenAPI import | `CREATE REST CLIENT (OpenAPI: '...')` | Generate REST client from OpenAPI 3.0 spec |
 | Business events | `CREATE BUSINESS EVENT SERVICE` | Event definitions |
 | Database connections | `CREATE DATABASE CONNECTION` | External SQL |
 | OData services | `LIST ODATA CLIENTS/SERVICES` | Read-only browsing |

docs-site/src/examples/rest-integration.md

@@ -557,6 +557,8 @@ Respond in {{Language}}.$$,
 | 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 | See OpenAPI import below | Auto-generate from spec |
+| Preview OpenAPI | `describe contract operation from openapi 'path';` | Preview without writing |
 
 ```sql
 create rest client Module.Api (
@@ -594,6 +596,27 @@ create rest client Module.Api (
 **Response types:** `json as $var`, `string as $var`, `file as $var`, `status as $var`, `none`, `mapping entity { attr = jsonField, ... }`
 **Authentication:** `none`, `basic (username: '...', password: '...')`
 
+### OpenAPI Import
+
+Generate a consumed REST service document directly from an OpenAPI 3.0 spec (JSON or YAML):
+
+```sql
+-- From a local file (relative to the .mpr file)
+create or modify rest client CapitalModule.CapitalAPI (
+  OpenAPI: 'specs/capital.json'
+);
+
+-- From a URL
+create or modify rest client PetStoreModule.PetStoreAPI (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
+);
+
+-- Preview without writing to the project
+describe contract operation from openapi 'specs/capital.json';
+```
+
+Operations, path/query parameters, headers, request body, response type, resource groups (from OpenAPI `tags`), and Basic auth are all derived automatically. The spec is stored inside the REST client document for Studio Pro parity.
+
 ## Published REST Services
 
 | Statement | Syntax | Notes |

docs-site/src/reference/capabilities.md

@@ -0,0 +1,33 @@
+-- SPDX-License-Identifier: Apache-2.0
+--
+-- OpenAPI import examples for CREATE REST CLIENT (OpenAPI: '...').
+-- These examples verify syntax and roundtrip behavior.
+
+-- ============================================================================
+-- DESCRIBE CONTRACT OPERATION FROM OPENAPI
+-- Reads a spec file and outputs the MDL that would be generated.
+-- No project connection required.
+-- ============================================================================
+
+describe contract operation from openapi 'https://petstore3.swagger.io/api/v3/openapi.json';
+
+-- ============================================================================
+-- CREATE REST CLIENT with OpenAPI source
+-- ============================================================================
+
+-- Minimal: spec drives everything (operations, BaseUrl, auth)
+create or modify rest client ClaudeKhodeLab.PetStoreMinimal (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
+);
+
+-- With BaseUrl override: replaces servers[0].url from the spec
+create or modify rest client ClaudeKhodeLab.PetStoreV4 (
+  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json',
+  BaseUrl: 'https://petstore3.swagger.io/api/v4'
+);
+
+-- Verify the created service is visible
+show rest clients in ClaudeKhodeLab;
+
+-- Describe the created service (roundtrip)
+describe rest client ClaudeKhodeLab.PetStoreMinimal;

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -15,6 +15,7 @@ type CreateRestClientStmt struct {
 	Documentation  string
 	Folder         string // Folder path within module
 	CreateOrModify bool   // True if CREATE OR MODIFY was used
+	OpenApiPath    string // Non-empty = spec-driven; operations come from spec not OPERATION blocks
 }
 
 func (s *CreateRestClientStmt) isStatement() {}
@@ -85,6 +86,14 @@ type DropRestClientStmt struct {
 
 func (s *DropRestClientStmt) isStatement() {}
 
+// DescribeContractFromOpenAPIStmt represents: DESCRIBE CONTRACT OPERATIONS FROM OPENAPI '/path/to/spec.json'
+// No project connection required; outputs the MDL that would be generated from the spec.
+type DescribeContractFromOpenAPIStmt struct {
+	SpecPath string
+}
+
+func (s *DescribeContractFromOpenAPIStmt) isStatement() {}
+
 // ============================================================================
 // Published REST Service Statements
 // ============================================================================

mdl-examples/doctype-tests/20-openapi-import-examples.mdl

@@ -5,6 +5,7 @@ package executor
 import (
 	"testing"
 
+	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/mdl/backend/mock"
 	"github.com/mendixlabs/mxcli/mdl/types"
 )
@@ -64,7 +65,7 @@ func TestShowVersion_NoSchemaHash(t *testing.T) {
 
 func TestHelp_Mock(t *testing.T) {
 	ctx, buf := newMockCtx(t)
-	assertNoError(t, execHelp(ctx))
+	assertNoError(t, execHelp(ctx, &ast.HelpStmt{}))
 
 	out := buf.String()
 	assertContainsStr(t, out, "MDL Commands")